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Call a routine from the extended TOS BIOS 


Initialize the MFP timer 


1, A Tutorial Introductio 


Congratulations on choosing the Mark Williams C compiler. Mark Williams C has the 
state-of-the-art power and flexibility that the professional programmer needs, but is 
simple exough for the begianer to learn quickly. 


Mark Williams C uses the latest advancements in compiler design, Tt parses programs 
by recursive descent and uses table-driven code generation io produce fast, dense 
cade. Then it performs extensive optimization to make the cade even better. Ease of 
use, full documentation, and compact generated code make Mark Williams C the right 
tool for the rapid development of your programs, 


Mark Williams C for the Atari ST is a member of the Mark Williams Company family 
of C compilers. Mark Williams Company compilers support many different environ 
ments and processors. The environments include the following: 


COHERENT 
CP/M-68K, 
ISIS-IT 
MS-DOS 
RMX 

TOS 
VAX/VMS, 


In addition to the 68000 family, the processors supported include: 


PDP-11 
28001 
28002 
3086 
80186 
80286 


What is in Mark Williams C? 


Mark Williams C is a uniquely powerful C programming system designed for the Atari 
ST. It consists of the following: 


1, The Mark Williams C compiler, plus an assembler, a linker, @ preprocessor, and 
other tools. 


2, A set of commands selected from the COHERENT operating system, including 
the MicroEMACS screen editor and the make programming discipline. 
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3. A full set of libraries, including the standard C litrary, a mathematics library, 
plus libraries that implement the Atari AES, VDI, and Line A routines. 


4. A set of sample programs, including full source code for the MicroEMACS 
editor, and text files to be used with the tutorials included your documentation. 


5. The Mark Williams micro-shell msh, a command processor designed to control 
the operation ef the compiler and its commands. 


‘Mark Williams C is designed to work through msh, a command processor that com- 
ines aspects of the Bourne and Berkeley C shells into a small but powerful program. 
With msh, you can perform numerous tasks to speed program development. Tt gives 
Mark Williams C unique power in developing programs for the Atari ST. 


Hardware requirements 


Mark Williams C is designed to be used on the Atari ST, either the 520 or 1040 
models. It can be used with the following hardware configurations: 


* An Atari ST with two disk drives, single- or double-sided, 
+ An Atari ST with one floppy disk drive and a hard disk. 


+ An Atari ST with one double-sided floppy disk drive, one megabyte of RAM, 
and a 500-kilobyte RAM disk, 


How to use this manual 


‘This manual is in four sections, Section 1, which you are now reading, is a tutorial 
introduction to Mack Williams C. It will show you how to use the micro-shell msh, 
tow to use its commands, how to compile programs, and how to use the various 
Hbraries available with Mark Williams C. 


section 2 is a table of all error messages produced by the compiler, the assembler, and 
the linker, 


Section 3 is the Lexicon. This is by far the largest part of the manual. The Lexicon 
sentains several hundred entries; each describes a command, a function, defines a C 
technical term, or otherwise gives you useful information, 


All of the Lexicon’s entries are in alphabetical order, and are designed to be ea: 
used. For example, if you want information on how to use the STDIO routines, 
Simply turn to the entry in the Lexicon on STDIO; there, you will find a list of all the 
STDIO routines, a description of each, and instructions on how to use them. Or, if 
you want information on how Mark Williams C encodes floating point numbers, 
Simply turn to the entry on float, There, you will find a full description of floating 
point numbers, Many Lexicon entries have full C programs as examples; all have full 
cross-references to related entries. 
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This tutorial will refer constantly to the Lexicon, If you are unfamiliar with a techni- 
cal term used in this manual, look it up in the Lexicon, Chances are, you will find a 
full explanation. If you are not sure how to use the Lexicon, look up the entry for 
Lexicon within the Lexicon. This will help you get started. 


Finally, the back of this manual has a tutorial for the make program building dis- 
cipline and the MicroEMACS screen editor. If you are unfamiliar with either of these 
tools, you will find that these tutorials will give you a good beginning in using them 


User registration and reaction report 


Before you go any further, Fill out the User Registration Card that came with your 
copy of Mark Williams C. Returning this card will make you eligible for direct 
telephone support from the Mark Williams Company technical staff, and ensures that 
you will automatically receive information about all new releases and updates. Many 
interesting developments and additions are planned for Mark Williams C. 


If you have comments or reactions to the Mark Williams C software or documentation, 
please fill out and mail the User Reaction Report included at the end of the manual, 
We especially wish to know if you found errors in this manual. Mark Williams Com- 
pany needs your comments to continue to improve Mark Williams C. 


Getting started 


The rest of this tutorial assumes that you have installed Mark Williams C on your 
Atari ST. If you have not yet done so, turn to the Release Notes that are included 
with this manual, There you will find directions on how to install Mark Williams C 
on your system; how to set up your system to run Mark Williams C properly; how to 
install the Mark Williams rebootable RAM disk; and how to run this product with un— 
usual configurations of hardware. 


If you wish to continue with this tutorial, return here after you have installed Mark 
Williams C on your system. 


Introducing the Mark Williams C micro-shell 

Mark Williams C is designed to run under a micro-shell, called msh. msh allows the 
passing of commands that are longer and more complex than can be handled easily 
through the GEM desktop; it also gives you an easy way to redirect the output of 
commands, pipe output to other commands, build and access tree-structured direc 
tories, and perform many other tasks to speed program development. msh comes with 
2 full complement of utilities and tools, to increase its usefulness. 
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Whet is msh? 


msh is a command processor. It teads and interprets commands, which can either be 
typed directly into msh, or stored in files, called scripts, that msh opens and reads. 
msh differs from icon-driven or menu-driven systems in that you type words into it 
rather than clicking items on the screen. If you have used COHERENT or UNIX, 
you will Lind that msh combines aspects of the Bourne shell and the Berkeley € shell 
to create a command processor that is simple yet powerful, 


How to enter msh 


Entering msh is easy, If you have a two-floppy disk system, just place your installed 
disk that is labelled “compiler” into drive A:, then use the mouse to open drive A: and 
display the contents of bin. If you have a hard disk, use the mouse to display the 
contents of bin on the logical drive on which you have stored the compiler, Point t0 
the icon labelled MSH.PRG and click the left button twice, 


The screen clears and a dollar sign ‘S' appears in the upper left-hand corner. The 
dollar sign is @ prope it means that msh is ready to accep! a command. 


To lest msh, type the following command: 


echo ¥e0 


Press the carriage return key, echo is a command that repeats all of the words, or ar- 
gumenis, that follow it, You will find that this command is quite useful in certain 
programming situations, As you can see, the argument feo appeared on the next line 
of the screen; then another dollar sign appeared, which signals that msh is ready to 
accept another command. 


Introducing MicroZMACS, the screen editor 


Mark Williams C includes @ full screen editor, called MicroEMACS. MicroEMACS 
allows you to divide the screen inta windows and edit different files simultaneously, 
It has @ full search-and-replace function, allows you to define keyboard macros; and 
hapa large set of commands for killing and moving text 


For a list of the MicroEMACS commands, see the Lexicon entry for me, the 
MicroEMACS command. At the back of this manual is a full tutorial that shows you 
how to use most of its commands, and contains @ number of exercises to help you 
sharpen your skill. 


You can begin to use the editor immediately, however, by remembering 2 half-dozen 
or so commands. To see how MicroEMACS works, do the following exercise: First, 
make sure that MicroEMACS js available to your system: if you have a system with 
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only floppy disks or with oaly a floppy disk and a RAM disk, make sure that the 
Scompiler" disk is ina disk drive. Now, type the following command: 


re hellose 


'As you can see, the screen clears, and an information line appears at the bottom, 
‘Type the following text, as it is shown here, Tf you make a mistake, simply backspace 
‘ver it and type it correctly, the backspace key will wrap around lines: 


main ¢ 
printt(thelto, wortd\n'd; 
> 


When you have finished, save the file by typing <ctrl-X><ctrl-S> (that is, hold down 
the control key and type ‘X’, then hold down the control key and type ‘S’). 
MicroEMACS will tell you how many lines of text it just saved. Now, exit from the 
editor by typing <etrl-X><ctrl-C>. 


Now, type Is -1, In a second, the 1is¢ command Is will print some information about 
the file, including its size, the date and time it was created, and its name. This proves 
that the file has been created and stored on disk. 


If you wish to change a file, just type the me command, as before: 
ne helto.c 


The text of the file you just typed is now displayed on the screen. Now, try changing 
the word hello to Hello, as follows: First, type <etrl-N>. That maves you to the nex! 
Tine. (The command <ctrl-P> would move you to the previous line, if there were 
one.) Now, type the command <ctrl-F>, As you can see, the cursor moved forward 
one space. Continue to type <ctrl-F> until the cursor is located over the letter ‘nh’ in 
hello, If you overshoot the character, move the cursor backwards by typing <ctrl-B>, 
When the cursor is correctly positioned, delete the *h' by typing the delete command 
<ctrl-D>; then type a capital 'H’ to take its place, Now, again save the file by typing 
-<ctrl-X><ctrl-S>, and exit from MicroEMACS by typing <ctrl-X><etrl-C>. 


With these few commands, you can load files into memory, edit them, create new 
files, save them to disk, and exit, This just gives you a sample of what Micr0EMACS 
can do, but it is enough to get you started, 


‘Setting the shell’s internal variables 


sh is designed to allow you to alter the way it operates, In effect, you can customize 
msh to suit your own needs. One way to do so is by using the set command. 


For example, you may wish to change the prompt from the dollar sign to something 
@lse. You can do this with the set command, To change the prompt to st>, type the 
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following command: 


Try it 
‘As you can see, the prompt changed as soon ss you pressed the carriage return key. If 


you type set by itself, a list of variables will appear. set allows you to define new 
variables, which are read by msh and interpreted. 


‘Try using set to create a “quick and dirty” command to clear the screen, As shown in 
the Lexicon article on screen control, the escape sequence that clears the screen on the 
Atari ST is <ese>E—that is, the escape character followed by a capital ‘E’. Note that 
‘| is the way the Atari ST echoes the escape character on the screen. To create your 
new command, just type the following into msh: 


set elastecho -n fe" 
Now, try typing: 

sis 
‘The dollar sign tells msh that the following string is a variable rather than a command. 
As you can see, the screen cleared and the cursor is now in the upper left-hand corner 
of the screen. ‘msh replaces cls with its defined value, and executes echo as if it has 
been typed in from the keyboard. 


To erase variable, use the command unset. For example, to erase the variable cls, 
typ 


unset ols 
Try typing Scls again. The shell sends you the message 
variable ‘ele! is not set 


which shows that els has been erased. 


Setting the environment 


msh manages a set of environmental variables. These can be used by programs that run 
under msh. For example, when the compiler driver cc begins its work, it looks for an 
environmental variable called LIBPATH, which tells ce which directories hold 
libraries, This system was designed to spare you the trouble of constantly giving 
programs the same information, For example, you need to set the LIBPATH variable 
‘only once; instead of telling ce where to look for the libraries every time you compile 
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a program, you can save space on the command line for more important items, such as 
fhe names of the files you wish to compile, 


‘The command seteny sets environmental variables. Try typing seteny. msh replies by 
printing a list of the environmental variables that have already been set. Most are set 
fh the file profile, which msh reads as it begins; this will be described in detail below. 


To see how a program can use an environmental variable, try resetting the environ- 
mental variable HOME. This variable is used by the change directory command ed 
when that command is entered without an argument. To set HOME to B:\, which is 
the root directory on drive Bs, type: 


seteny NOHE=b#\ 


Now, type the following commands: 


pad 


The first command changes directories for you; because you did not tell it which 
directory to go to, it moved you by default to the directory named by the HOME en- 
vironmental variable. pwé prints the working directory; as you can see, the current 
directory is b:\, which is the directory that ed moved you to, 


The command unseteny erases environmental variables. For example, you can erase 
the variable TIMEZONE with the following command: 


unseteny TH 


ZONE 


Now, type seteny again. As you can see, the TIMEZONE environmental variable is 
no longer present, 


Directories 


You have probably notived by now that msh uses tree-structured directories. This 
means that its directories branch out from one another; each directory can contain 
files ano sub-directories that themselves can contain files and directories. One direc 
tory is called the root directory; this is the name of the device. For example, the root 
directory for drive A is called a:\, The root directory can have one or more sub- 
Girectories; these are also called child directories because they all stem from the same 
Parent directory. Thus, while a directory can have many child directories, it can have 
only one parent directory. 


Note thet two dots“. stands for the parent directory, The following examples will 
show how to use this abbreviation, 
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msh comes with a full set of commands to create and remove directories, and copy, 
rename, move, and remove files. As you will see, these are quite easy to use, and 
quite powerful 


To begin, you can make a directory with the command mkdir. To create a directory 
called stuff, type: 


kin ature 
Try it, If you wish, you can specify a fall path name to create a subdirectory in a 
directory other than the one you are currently in. For example, to make the sub- 
directory temp in the directory stuff, just type: 
kar stuf#\eenp 
Try it, Now, tell the list command, Is, to show you the contents of stuff, as Follows: 
la stuff 
As you can see, Is printed the name of the subdirectory you just created. 
‘The remove directory command rmdir allows you to erase directories. To remove the 
directory temp, use the following command: 
endir etuff\tenp 


If temp had had files and subdirectories in it, rmdir would have given you an error 
message, This is to help prevent you from accidentally erasing valuable files. 


Renaming, moving, copying. and removing files 
As mentioned above, msh has a number of commands to help you handle files. 


‘The move command my lets you rename a 


le, The following example creates a file 
called smith, and then renames it jones: 


echo stuff >enith 
By saith jones 


Note that if the file jones had already existed, it would have been removed and the 
file smith given its name. 


You can also use my to move a file from one directory to another, For example, the 
command 


inv Jones stuff 


will move the file jones from the current directory to the directory stuff. 
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‘As mentioned above, two periods “.” is shorthand for a directory’s parent directory, 
‘Thus, (0 move the file jones back from the directory stuff to the current directory, 
type the following command: 

nv stutf\ jones 


If you type Is without any arguments, it will show the contents of the current direc 
tory; it should show that the file Jones has been returned to the current directory. 


The copy command cp will copy one or more files for you. To copy the file jones 
back into the file smith, type 


op Jones smith 


As with the my command, if the file smith had already existed, it would have been 
removed and the new copy of jones given its name. 


ep can also copy several files at once into another directory. To copy the files smith 
and jones into directory stuff, type: 


ep saith jones stuff 


ep is intelligent enough to know that stuff is a directory; it will copy smith and jones 
Into stuff and give the copies the same names as the originals, 


‘The command rm removes a file, To remove the files smith and jones from directory 
stuff, type: 


rm stuff\enith stuff\jones 


you type mm without an argument, it will print an error message on the screen, 


Redirecting input and output 


msh allows you to change, or redirect, the place from which a program receives input 
and the place to which it writes output, The technical term for this is 1/0 rediree- 
tion. 


The C language normally defines three channels through which data can be passed: 
the standard input, the standard output, and the standard error. The standard input 
and the standard output, respectively, are connected to the keyboard and the screen 
by default. The standard error is the device on which error messages appear, by 
default, it is the screen, Note that the terminal screen continues to be the standard 
error, even if the standard output is redirected elsewhere, 
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A redirection operator is a character that tells msh to redirect the standard input, stan 
Gard output, or standard error somewhere other than its default. The following lists 
the more commonly used of msh’s redirection operators: 


> file Redirect the standard output of a command into file. If file already ex- 
jsts, replace its contents with the output of the command, For example, 
typing 


echo halle Sterpfile 


‘opens the file tempfile and then echoes the argument hello into it. If the 
file tempfile already exists, its contents will be replaced with the string 
hello, 


>& file Redirect both the standard output aad the standard error of a command 
into file, 


>» file Append the standard output of a command onto file. If file does not ex- 
jst, create it and fill it with the output of the command, For example, the 
command 
echo goodbye >>tenpfile 


appends the word goadbye to the end of the file tempfile, which you 
created in the earlier example. 


>>& file Append both the standard output of a command and the standard error 
Gato file, If file does not exist, create it and fill it with the output and 
diagnostic messages generated by the command. 


<file ‘Use the contents of file as the standard input for a command. 
For a full list of redirection operators, see the entry for msh in the Lexicon 


Redirecting to peripheral devices 


‘As you can see from the examples in the previous section, redirection is most often 
performed into or out of files on disk, However, as will be described below, C treats 
peripheral devices as if they were files; therefore, you can use a redirection symbol to 
send material to, say, the printer or the serial port. 


For example, if you have a printer plugged into your Atari ST, turn it on and type the 
following command: 


echo helo >prn: 


‘This types the word hello on your printer, 
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Logical devices 


FOS, the Atari's operating system, has built into it three logical devices. msh can use 
these logical devices in exactly the same way that it handles files: it can open them, 
fied data (rom them, write data to them, and close them again. The logical devices 
ire as follows: con:, Which is the console’s screen: prn:, which is the printer port; and 
Gus, which is the auxiliary, or serial, port, These are described in more detail in 
their respective Lexicon entries, 


Redirecting data to the printer port can be quite useful; for example, you can print 
iiings of your programs. Try this exercise, Turn on your printer, and type the 
following command: 


pr -n hello.e >pen: 


As you can see, a listing of your program appears on your printer, with each line 
numbered for your convenience. The command pr formats material for printing, and 
its -m option tells it to insert line numbers. pr is, of course, described more fully in 
the Lexicon. 


File-name substitutions 


Often, typing in the names of a group of files is tedious. For that reason, msh allows 
you to deal with files in groups, by using file-name substitutions, 


msh can use the punctuation marks [ ] ? * ( and } to substitute for all or part of a file's 
name, The following descrites what each does 
Vist, faz] 


In the first form, this looks for, or matches, any of the characters J, i, s, or (; in 
the second form, it matches all of the cheracters between aand z. 


Try the following exercise, First, use the echo command to create three sample 
files, as follows: 


eth stuffl files 
fon stuff? >i Leb 
fone stuftS orilee 


‘The following command tells the list command Is to find these files in the cur- 
rent directory: 


\s #iteteber 


As you can see, the shell expanded file{abel into 
handed to Is to find. 


b filee, which it then 


u 
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The next exercise uses the concatenation command cat to display the contents 
of these three files. Type the following: 


cat filetarcl 


msh expands filela-el into file a through ¢, inclusive, or filea fileb filec. As you 
can see, cat opened all three files and displayed their contents for you on the 
screen, 


‘Match any character. For example, typing 

Is file? 
will list every program in the current directory that is named fileanyletter. 
Note that the ‘?’ is a wildcard character; see the entry for wildcard in the 
Lexicon for more information. 
Match any character, any string of characters, or no character. Try typing 


ls tee 


‘As you can see, Is lists all files whose names end with the character ‘a’ through 
‘O. “The asterisk is also a wildcard; see the entry on wildcards in the Lexicon for 
more information, 


(ise) 


12 


Use the enclosed letters Li,s,t to form a series of words. For example, the com- 
mand 


ls Filete,b,ed 
is equivalent to typing 
lo files filed filee 


To see how this differs from the ‘[' ‘T’ characters described above, type the 
following commands: 


sche feotabel 
fecho Foote, bye) 


‘The first command prints 
feotabel 


whereas the second returns 
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Quoted sirings 


At times, you want to pass a string to a command literally, without its being inter- 
preted or matched by the shell. Passing a siring in this manner is called quoting it, 
Because you indicate the special character of the string by enclosing it within quota 
tion marks or apostrophes. (An “apostrophe” is also known as a “single quote”; the 
apostrophe is found on the same key as the quotation mark, directly to the left of the 
carriage return key.) 


Note that if you quote a string with quotation marks instead of apostrophes, msh will 
treat white space as part of the string, but further expand variables within the string. 
‘To see how this works, type the following exercise: 


at 


rz 


set Beans" 
‘ho SA sa 
echo "$A se 
che 184 3 


As you can see, in the first case echo expanded $A and $B, but threw away the extra 
spaces between them, In the second case, it expanded $A and $B, and preserved the 
extra space between them; in the third case, echo preserved the extra space between 
‘SA and SB, but did not expand them, 


Joining and separating commands 


msh uses a number of different punctuation marks, or operators, to join and separate 
commands. Each operator performs a specialized task, as follows: 


3 Commands separated by a semicolon *! are run one after the other. This allows 
you to type more than one command on the same line, for convenience, 


Form a pipe; that is, pass the standard output of the command on the left into 
stendard input of the command on the right, Try the following example. First, 
turn on your printer, and then type: 


le ol | pe pent 


‘As you can see, the names of the files in the current directory are being printed 
‘on your printer. The command Is first read the names of the files in the current 
directory, (The switch -1 tells Is to write the names in the long format, which 
gives you extra information, such as the size of each file.) Normally, Is writes 
its ourput onto the soreen; the pipe symbol ‘', however, told Is to pass its output 
{0 the pagination command pr, which used it as input. ‘Finally, pr redirected its 
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output to the logical device prn:, so that it appeared on your printer. 


As you can see, pipes and redirection symbols allow you to construct chains of 
comimands that are quite powerful, yet quite easy to use. 


|& Form a pipe that passes to the command on the right both the output and any 
error messages from the command on the left. 


The profile file 


Whenever you invoke msh, it automatically reads a file called profile and executes.all 
of the commands it finds there, By altering your profile, you can customize msh to 
suit your preferences and the tasks at hand, 


The following is a sample profile: 


Pre, tos, Et 

seteny LispAtieserive\lib, Sdrive\bin, 
Seven THPDIRScve\ tre 

setenv INCDIR=Sdrve\ include 

Sseteny TIMEZONE=CST:0:c0T 

set pronpt='S | 

Set hietery=8 


The first line, 


set drives 


sets the variable drive to ax; this means that the variable drive will be interpreted as 
a: by msh, 


The next line, 
‘setenv PATHC.bin, ,Sdrfve\bin,Sdeive\ccomand 


set the PATH environmental variable, which tells msh where to find executable files, 
The first directory, -bin, stands for msh itself; this tells msh to check and see if the 
command you have typed in is built into msh itself. The rest of the command 


a ddrive\bin, Sdrive\ecnmandt 


tells msh to look for executable files first in the present directory (as indicated by the 
two commas with nothing between them), then in the directory a:\bin, and finally in 
the directory a:\command (remember that $drive is interpreted to mean az). Note that 
unless this line is set correctly, msh will not be able to execute the rest of the com 
‘mands in profile. 


4 Mark Williams C 


Tutorial Introduction 


‘The next lines, 


rg, tos, tte 
setenv Lispatiiesarve\lib, Sdrive\bin, 


set the environmental variables that msh exports to various other commands. Each 
variable is described at length in the Lexicon. 


Finally, the lines 


set prompt 
set histor 


set the prompt to a dollar sign ‘$', and set the history buffer to hold the last eight 
commands entered, This is used with the history command; for more information on 
this command, see the Lexicon entry for msh. 


‘You can use the profile file to fine-tune msh so that it carefully suits your needs and 
preferences, 

After a while, you will grow familiar with msh and will want to use its power more 
fully, See the entry for msh in the Lexicon for a complete description of what it can 
do, 

For more information about the commands that come with your copy of Mark 
Williams C, see the Lexicon entry for commands; this entry lists all of the available 
commands and briefly describes what each one does. Each command has its own 
entry in the Lexicon, which will give you all the information you need to use it 
properly, 


Compiling with Mark Williams C 
‘This section describes how to compile C programs with Mark Williams C. 


In brief,a C compiler transforms files of C source code into machine code. Compile 
tion is complex and involves several steps; however, Mark Williams C simplifies it 
with the ce command, which controls all the actions of the compiler. 


Compiling from the GEM desktop 


Before you begin, note that Mark Williams C was designed to be run through the 
micro-shell msh; however, you can run ce and the compiler from the GEM desktop. 
To de so, perform the following steps: 
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1, Rename the file cc.prg to ec.tip. 
2. Mave the following files plus your source code into the same folder: 


ce.ttp 
ccO.prg 


Also move all of the header files, which have the suffix .h. 
3. Use the mouse to double-click the icon labelled CC.TTP. When the Open ap- 
plication box appears, enter the names of the files you wish to compile, 


Note that the micro-shell_msh preserves the case of arguments passed to Mark 
Williams C. The GEM-DOS desktop, however, translates all arguments to upper case, 
in some instances changing their meaning. 


Compiling through msh 


The rest of this section assumes that you are running Mark Williams C under the 
micro-shell msh, 


For en example of how cc works under the micro-shell msh, try compiling the 
program called hello.c, which you typed in earlier to test the MicroEMACS screen 
editor. Type the following command: 

ce -V hellowe 


The switch -V tells ec to print a brief description of each action it takes. As you can 
see, cc guides the program through all phases of compilation, invokes the linker Id, 
and links in all necessary routines from the libraries to produce a file called hello.prg, 
that is ready to execute, 
To try out your newly compiled program, type hello. The program will print 

Hello, wortd 


om your screen. 
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The phases of compilation 


You probably noticed that when hello.c was being compiled, cc invoked a number of 
different programs. This is because Mark Williams C is not just one program, but a 
number of different programs that work together to produce an executable file for 
you, Each program performs a phase of compilation. The following summarizes each 
phase: 


cpp The C preprocessor. This processes any of the * 
or #ifdef, and expands macros. 


directives, such as #include 


ccd The parser. This phase parses programs; it uses recursive descent to translate 

the program into a parse-tree format, which is independent of both the lan 
guage of the source code and the mictoprocessor for which code will be 
generated. 


The code generator, This phase reads the parse tree generated by ecO and 
translates into machine code. The code generation is table driven, with entries 
for each operator and addressing mode. Although this phase is followed by an 
optimizer, it is designed to generate excellent code that needs minimal op- 
timization. 


The optimizer/object generator. This phase optimizes the generated code and 
writes the object code. It eliminates common code, optimizes span-dependent 
jumps, and removes jumps to jumps. It also scans the generated code 
repeatedly to eliminate unnecessary instructions, then writes the object file. 


The compiler also includes a fifth phase, called cc3, which is a disassembler, 
‘This phase writes an output file in assembly language. This phase is optional, 
and allows you to examine the code generated by the compiler. If you want 
Mark Williams C to generate assembly language, use the -S option on the cc 
command line. 


Unless you specify -S on the ce command line, the compiler outputs an object module 
that is named after the source file being compiled. This module has the suffix .o, An 
object module is nor executable; it contains only the code generated by compiling a C 
Source file, plus information needed to relocate parts of the code before routines from 
the C libraries are linked into the program. See the entry on object module in the 
Lexicon for more information. 


As the final step in its execution, cc calls the linker 1d to produce an executable 
Program. In the previous example, the linker combines the odject module hello.o 
with the function printf from the standard C library to produce the executable 
Program called hello.prg, The suffix .prg indicates that the file is executable, 
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Edit errors automatically 


Often, when you're writing a new program, you face the situation where you try to’ 
compile, only to have the compiler produce error messages and abort the compilation. 
‘You must then invoke your editor, change the program, close the editor, and try the 
compilation over again. This cycle of compilation—editing—recompilation can be 
quite bothersome, 


To remove some of the drudgery from compiling, the ce command has the automatic 
or MicroEMACS option, ~A. When you compile with this option, the MicroEMACS 
screen editor will be invoked automatically if any errors occur. The error or errors 
generated during compilation will be displayed in one window, and your text in the 
other, with the cursor set at the number of the line that the compiler indicated had 
the error. 


Try the following example. Use MicroEMACS to enter the following program, which 
‘you should call ertor.c: 


main € 
brincforwello, wertde 


> 


Note that the semicolon was left off of the printf statement, Now, try compiling er- 
ror.e with the following ee command: 


ce “A errar.e 
You should see no messages from the compiler, because they are all being diverted 


into a file to be used by MicroEMACS. Then, MicroEMACS will appear automati- 
cally. Tn one window you should see the message: 


3: missing 


and in the other you should see your source code for error.c, with the cursor set on 
line 3. 


If you had more than one, typing <etrl-X>> would move you to the next line with an 
error in it; typing <etrl-Xsz would return you to the previous error, Note that with 
some errors, Such as those for missing braces or semicolons, the compiler cannot al- 
ways tell exactly which line the error occurred on, but it will almost always point to 8 
line that is near the source of the error. 


Now, correct the error. Close the file by typing <ctrl-Z>. ce will be invoked again 
automatically, to produce a normal working executable file. Note that ce will con- 
tinue to invoke the MicroEMACS editor either until the program compiles without 
error, of until you exit from the editor ty typing <etrl-U> followed by <etel- 
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Xp<ettl-C>, 


Compiling multiple source files 


Many programs consist of more than one source file. For example, the sample 
program factor, which is provided with Mark Williams C, consists of the files factor.c 
and atod.c. To compile a program with multiple source files, just type each file name 
as a separate argument on the ee command line: 


cco fector.e atod.¢ -{m 


This command compiles both source files, The argument -Im tells ce to include 
soutines from the mathematics library libm when linking the object modules to 
produce an executable file. This option must come after the names of all of the 
source files which reference the library, or it will not work properly. 


When the cc command line includes several file name arguments, cc by default uses 
the name of the first to form the name of the executable file. In the above example, 
ce produces the non-executable object modules factor.o and atod.o, and then links 
them together to produce the executable file factor.prg. 


Naming executable files 


To give the executable file a name other than the default, use the -0 (output) option, 
followed by the desired name. For example, when Mark Williams C compiles the 
source file hello.e, by default it assigned the executable file the name hello.pre. 
Should you wish the executable file to have the name hello.tos, use the following 
comman 


ce -2 hallo. tes hellove 


Linking without compiling 


If you are writing a program that consists of several source files, you probably will 
Want to compile the program, test it, and then change one or more of the source files. 
Rather than recompile all of the source files, you can save time by recompiling ony 
the modified files and relinking the program. 


For example, suppose you modified the factor program by changing only the source 
ile factor.e, To recompile, you can use the following command: 


te factorse atod.e “bm 


The option -Im tells ec that this program needs to have the mathematics library libm.a 
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included when it is linked. 


In this example, the first two arguments are the C source file factor. and the object 
module atod.o, rather than the source file atod.c. ec recognizes that atod.o is an object 
module and simply passes it to the linker without compiling it. You will find this 
particularly useful when your programs consist of many source files, and you need to 
compile only a few of them. 


‘To simplify compiling, especially if you are developing systems that use many source 
modules, you should consider using the make command that is included with Mark 
Williams C, For more information on make, see the entry in the Lexicon, or see the 
tutorial for make that appears later in this manual. 


Compiling without linking 


Attimes, you may find it useful to compile a source file without linking the resulting 
‘object module to the other object modules or the libraries. You would do this, for 
example, if you wanted to compile a module to insert into @ library. Use the ~¢ op- 
tion to tell ce not to link the compiled program. Later, you can use another ce com- 
mand to link the program. For example, if you wanted just to compile factor.c 
without linking it, you would type: 


ce ve factor. 


To link the resulting object module with the object module atod.o and with the ap= 
propriate libraries, type the following command: 


ce factor.o atec.o -tm 


Floating point output 


A large amount of code is required to print floating point numbers, Because most C 
programs do not need to print floating point numbers, the conversion routine in the 
standard C library merely prints the message 


You mist compile with the -f option 
20 Include printf) floating point. 


To include the routines that print floating point numbers, use the -f option with the 
ce command, 


20 Mark Williams C 


‘Tutorial Introduction 


Assembly language files 


c makes most assembly language programming unnecessary; however, you may with 
to write small parts of your programs in assembly language for greater speed or to 
provide access to processor features that C cannot use directly. Mark Williams C in- 
bludes an assembler, named as, which is described in detail in the Lexicon, 
To compile a program that consists of the C source file eprog.c and the assembly lan- 
guage source file aprog.s, simply use the ee command in its usual manner: 


ce corog.c apreg.s 


ce recognizes that the suffix .s indicates an assembly Janguage source file, and as- 
sembles it with the assembler as; then it links both object modules to produce an ex- 
ecutable file. 

‘The Lexicon entry for the TOS macro Setexe includes an example that demonstrates 
how to compile assembly language files with C-language files, 


Generating assembly language output 
The ce switch -S directs the C compiler use the disassembler cc3 to compile into as- 
sembly language rather than an object (.0) module, You may wish to examine these 
assembly-linguage listings to debug a program, or examine how a particular library 
routine does its work. 


Changing stack size 


The size of the stack cannot be altered while a program is running. By default, the 
linker sets the stack size to two kilobytes; however, a highly recursive function may 
cause the stack to grow to the point where it invades other data areas. This will cause 
your program to work incorrectly. 


Should your program need more than two kilobytes of stack, include the following 
slobal statement anywhere in your program: 


long _stksize = 7th; 


where 1 is an even decimal number of bytes. 


The ce command is summarized in the Lexicon, under the entry ec. Each phase of the 
Compiler has its own entry. The entry for as gives full information on how to use this 
tool, plus listing the set of 68000 machine instructions. 
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Using the Mark Williams C Libraries 


‘Mark Williams C includes a number of libraries whose routines perform many useful 
tasks, These include standard input and output (STDIO), memory management, sor- 
ting, and searching: mathematics functions; and accessing the GEM AES and VDT 
routines, as well as the Atari Line A functions. 

Mark Williams C also includes the archiver ar, which helps you to update the current 
libraries or create your own libraries. 


The following paragraphs will introduce some of the routines included in the Mark 
Williams C libraries, show you how to include them when you compile a program, and 
describe briefly how to use the archiver utility. 


Strings and string handling 


A commonly used data structure is the character siring. The usual run-time represen~ 
tation for a string is an array of characters delimited by a NUL character. 


If you need to move characters, use the library routine strepy. This function takes two 
arguments: the first points to where the string will be copied to; the second peints to 
here the string will be copied from, strepy then copies all characters, through NUL, 
and returns the first argument. 


‘You can measure the length of a string by using strlen. This function takes one argu- 
ment, 2 pointer to a string, and returns the number of characters in the string, ex- 
cluding the NUL that concludes the string. 


streat concatenates strings (.e., joins them together). It takes two pointers to strings 
ag arguments, and appends a copy of the second string to the end of the first, The 
First siring is assumed to have enough exta space at the end to hold the new charac- 
ters. streat returns a pointer to the new result, which is delimited with NUL, 


Often, strings must be compared. This must be done, for example, if an array of 
strings ig being sorted. strcmp compares strings. It takes two arguments, both 
pointers to strings, and compares the strings they point to. stremp returns a number 
less than zero if the first string is less than the second string, using native machine 
character comparisons; one equal to 0 if the two strings are equal; and one greater 
than (if the first string is longer than the second string. 


Applications that deal with fixed-length strings can use the routines stracat, stenepy, 
and straemp, They perform the same functions as their variable-length counterparts, 
however, all take a third argument that specifies the maximum length of the string. 


Sce the entries in the Lexicon for these routines and for string; these will give you ex- 
amples of how to use them ina C program. 
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Input and output 


‘The standard library provides routines that perform input and ouput, or 1/0, at a 
number of levels. Data can be transferred byte-by-byte, word-by-word, by string, 
by block, and in a formatted manner. For more information and examples of how to 
use these routines, see the Lexicon entry for STDIO. 


The standard 1/O header file stdio.h includes a type definition, or typedef, for the 
FILE type. A FILE is a structure that contains all of the information needed by the 
1/O routines to perform 1/O operations on a connection, A pointer to a FILE is the 
external name of an I/O stream, and is passed to the various routines in the 1/0, 
library 10 specify which stream participates in the transfer. Note that a FILE can 
either be a file of data written on a disk or a logical device as defined by the 
operating system, e.g., the keyboard, the serial port, or the parallel port. C, like msh, 
Gioes not distinguish between logical devices and files on disk—it regards them all 
merely as sources of data for it to handle, 


To open a file and allocate a FILE type, use the routine fopen, Tt takes two arguments: 
the first is a string that contains the name of the file to be opened, and the second isa 
string that specifies the access mode required. The mode is one of the following: r, 
for plain reading: w, for plain writing; rtw, read plus write, or update; or a, for ap- 
pend. In addition, the mode string can contain the character b, for binary, which 
specifies that this is a binary stream; this ensures that newline characters will not be 
mapped into a carriage retura/line feed sequence. 


Af the mode is w or a and the named file does not exist, it will be created. If the mode 
is w and the file does exist, it will be truncated to zero length. If the FILE could be 
gpened, fopen returns a pointer to a FILE object; if it could not be opened, it returns 
NULL. 


When all processing on a FILE is completed, the file must be closed by calling felose. 
This routine takes one argument, a pointer to a FILE. ll buffers are flushed and 
released, and the connection is detached, 


The routine exit will autometically close all open files and return control of the com- 
Duter to TOS. Your programs should always call exit when they are finished. 


Se the Lexicon entries for exit, fopen, felose, and STDIO for more information, and 
for examples of how to use these routines. 


Byte-by-byte 1/0 


The lowest tevel of 1/0 is the byte-by-byte level, Here, data are read from or written 
to a FILE one character at a time. All higher-level I/O routines use these byte-by- 
te routines to read and write data. 
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‘The most basic read routine is gete(/p). This function takes one argument, a pointer 
to a FILE, and returns an int that contains either the next character from the FILE or 
the end-of-file signal EOF. EOF is defined in the header file stdio.h. 


In ASCII mode, gete throws away all carriage return characters (0x01); the line feeds 
at the end of the lines (0x0A) mark the end of the lines, because the ‘\n’ in C is equal 
to OXOA. In binary mode, all characters are passed without interpretation. 


‘The routine gotchar is equivalent to gete(stdin); it reads characters from the standard 
input FILE, which is normally the keyboard. 


The routine ungete(c, ff) returns ¢ to the FILE fp. This is useful for looking ahead at 
the next input character and then returning it to the input file. Only one character 
can be “unread” with ungete. 


The most basic write routine is pute(c, fp). This takes two arguments: c, which con— 
taing the byte to be written: and fp, which points to the output FILE. ‘pute returns 
the first argument unless write error ocours, in which case it returns EOF. 


putchar(c) is equivalent to pute(c, stdout). It writes characters to the standard output 
FILE, which ig normally the video display. 


See the Lexicon entries for these routines, which contain more information snd ex- 
amples of how to use them in C programs, 


Word-by-word 1/0 


‘A program may read the next word (16-bit object) from a FILE by using the routine 
getw(fp). This routine takes one argumeat, a pointer to a FILE; it returns the word 
read. 


Note that getw can return any bit pattern, including control characters. A special 
character like EOF can appear even in the middle of a file. Therefore, to prevent the 
file from being truncated accidentally, your program must test for end of file by 
using the macro feof(fe), from stdio.h. This macro looks et the FILE pointed to by 
‘fp and returns true if the last call to getw ran into the end of the file. 


If file has an odd size, the last call to getw will return the data and an error will be 
posted to the FILE, This error may be detected by using the ferror(/p) macro, End 
Of file alone is posted if'a call to getw produces no data, 


In a simitar manner, putw(w, fp) writes word to a file. The ferror macro must be 
used 19 check for 1/0 errors. 


See the Lexicon entries for these routines for examples and more information 
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String 1/0 


‘A number of routines perform 1/O on strings. The most basic one is fgets(b. 1, fp). 
It reads a string delimited by a newline character from the FILE pointed to by fp, and 
stores it into the array of characters 6. The newline character is transferred to the 
buffer, NUL is placed in the buffer immediately after the newline. ‘The integer 7 
specities the length of the buffer; this prevents fgets from writing beyond the array i 
a long line is encountered in the input. fgets returns & if any characters were read 
and NULL if not. 


‘The routine gets(string) reads a newline-delimited string from the standard input 
siream and stores it within the array of characters string, Unlike fgets, gets deletes 
the newline character from the end of the string and replaces it with NUL, 


The most basic string output routine is fputs(owpue, fp). This routine writes the 
string ouput into the FILE pointed to by fa. puts(siring) writes string, followed by a 
newline, onto the standard output, 


For more information and examples of how to use the string I/O routines, see their 
entries in the Lexicon. 


Block 1/0 


‘The standard library provides facilities to transfer blocks of memory to and from user 
programs, These are most often used on binary streams to move raw binary informa- 
tion to and from files; however, they may be used on ASCII streams without altering 
their data, with the possible exception of altering newline interpretation. 


The function fread(b, size, n, fp) reads n objects of size bytes into the buffer pointed 
to by b from the FILE pointed to by fp. It returns the number of items actually read. 


Likewise, the routine fwrite(6, size, #, fp) writes n objects, each size bytes long, from 
the buffer b to the FILE pointed to by fp. Itreturns the number of items written, 


See the Lexicon entries for fread and fwrite for examples and more information. The 
feof and ferror macros can be used to check for end of file and transmission errors on 
block reads and writes. 


Formatted 1/0 


Routines are provided that permit formatted 1/0 to and from FILE streams. Data 
may be read from and written into a number of formats and bases (decimal, octal, 
hexadecimal); strings may be truncated or padded; and fields may be justified to the 
left or to the right. 
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Although these routines are usually used on ASCII streams, they work perfectly well 
on binary streams; they are, after all, interfaces to pute and gete. 


‘The formatted 1/O routines printf and scanf are complex. The details of all their for 
matting options are described in detail in the Lexicon entries that describe them. 


Briefly, all formatted 1/0 routines work by interpreting one argument as a format 
string, This string consists of format specifications, each of which is introduced by a 
8 peivent-sign character ‘%', plus other characters that specify the type of Formatting 
to do. As each format specification is encountered in the format string, an argument 
is exicacted from the list of parameters of the formatted 1/O routine and interpreted 
in a fashion determined by the format specification: the first format specification 
takes the first argument, the second takes the second argument, and so on, The type 
of the argument must agree with that expected by the format Specification; if this is 
not the case, such as when a long is placed in the argument list where an int is ex- 
pected, the fesult is undefined. Characters placed between the quotation marks that 
do not belong to a format string (e-g., commas or spaces) are printed out literal: 


For more information on how to use print and scant, see their entries in the Lexicon, 


Random access 


All of the examples seen so far deal with sequential access FILE streams; however, the 
1/0 library supports random access transfers as well. Associated with every FILE is a 
seek pointer. This pointer starts at the beginning of the file or, when a stream is 
opened for appending, at the end of a file; as data are read from or written to the 
FILE, it moved forward through the file. 


‘You can obtain the value of this pointer by using ftell(fn). Tt returns the current 
value of the seek pointer for the FILE pointed to by fp. 

The seek pointer can be moved about in the file with the routine fseek(/p, where, 
how). This resets the seek pointer in the FILE pointed to by /p to where, alsoa 32-bit 
integer. The how argument specifies if the seek is relative to the beginning of the 
file(how = 0), to the current-seek position (how = 1), or to the end of the file (how = 
2), fseek returns 0 on success or -1 on failure. 


Some FILE streams cannot perform random access operations; these include the ones 
attached to the videodisplay, the serial port, or the printer port, 


Returning the seek pointer to the start of a file is eased by the routine rewind(/p). 
‘This routine is equivalent to fseek(/p, OL, 0), 


See the Lexicon entries for these routines for more information and examples. 
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Sorting 


often, data must be sorted. The standard library contains two sort functions. These 
Fonetions are general, in that they implement only the skeleton of the sort algorithm. 
‘The user must provide a comparison function and tell the sort function the size of the 
objects being sorted. 


The asort(b, m, size, f) routine implements Hoare's quicksort algorithm, The argu- 
ment 6 points to the base of the block of data being sorted, and the » argument 
specifies number of elements to be sorted, Each of these objects has size bytes; the 
Toutine needs the size to be able to move the objects around and to update its internal 
pointers, f points to a function that performs comparisons. The shellsort(b,, size. J) 
Foutine has exactly the same calling sequence as qsort, but uses Shell's sorting method. 


gsort can use large amounts of stack, because it isa recursive algarithm. To alter the 
size of the stack, include the following global statement: 


long _stacksize = ml; 
where mn isan even number of bytes. 


For more information on these routines and for examples, see the entries for qsort and 
shellsort in the Lexicon. 


Dynamic memory allocation 


When you build linked data structures or deal with arrays whose size can be deter- 
mined only at runtime, it is helpful to be able to allocate blocks of memory dynami- 
cally. The standard functions malloc, calloc, and free implement a general-purpose 
memory allocation system used to allocate buffers, 
To allocate memory, use malloc(). This routine allocates a block of memory of at 
least : bytes and returns a character pointer to it. The block may be larger than re- 
quested, if allocating the exact size would create a very small, and probably unusable, 
Block on the list of free memory. The block contains random information; it is not 
itialized in any way. If no memory is left in the free space pool, a NULL pointer 
will be returned, 
calloc(n, size) uses malloc to allocate a block of memory large enough to hold » ob- 
Jects of size size; this memory is then zeroed. If there is insufficient free memory, a 
NULL. pointer is returned, 


Blocks of memory that are no longer needed can be returned to the free pool by pas- 
Sing a pointer to the block to free(p). This routine places the block back in the free 
list and merges adjacent free areas into single, larger free areas. [t is a serious error to 
Pass an incorrect pointer to free. No checking is done; a subsequent call to one of the 
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allocation functions will probably retura a very strange value. 


Mathematics routines 


‘The mathematics library libm.a contains 4 number of transcendental functions. They 
will calculate the sine, cosine, and tangent of a figure, plus their inverses and hyper= 
bolic forms; calculate both natural and decimal logarithms; compute powers and ex— 
ponents; and compute Bessel Functions, 


The Lexicon entry for the mathematics library introduces these functions; each has its 
own entry in the Lexicon, which include fuller descriptions and examples. 


Note that to use a mathematics function, you must name the mathematics library on 
the cc command line when you compile your program. For example, if the program 
sample,c contains a mathematics function, use the following form of the ce command: 


cc sarpleve -im 


‘The option -Im indicates that you want the mathematics library to be included at link 
time. Note that this option must come at the end of the ec command, or the program 
\will not link properly, 


bios, xbios, and gemdos functions 


Mark Williams C allows you to call directly the Atari ST's bios, xbios, and gemdos 
routines. Strictly speaking, these are not library functions; rather, they use routines 
that are built into the Atari BIOS to perform operating system tasks. 


‘The bios routines perform basic 1/0, such as managing the peripheral devices and disk 
drives, xbios routines extend the normal bios functions, to provide access to system. 
clocks, the sound chip, the intelligent keyboard manager, the mouse, ond other 
devices. gemdos routines perform such tasks as 1/O with the parallel and serial ports, 
managing the disk drives, performing file 1/0, managing dynamic memory, and. 
managing processes. 


These routines can be called directly through C programs. All are defined in the 
header file osbind.h, which is included with your distribution, 


‘The following program demonstrates how the xbios function Setcolor is used in a C 
program. It inverts the color setting on a monochrome monitor: 

include <osbind. n> 

mein) € 


fnt color = seteolor(o, -197 
seteolar(a, svectorky; 
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¢ information on these routines, see the entries for bios, gemdos, and xbios in 


For mors 
the Lexicon. 


UNIX rowines 


‘The standard library includes a number of routines that mimic a variety of UNIX 
gystem calls, to manipulate files. These work in a somewhat different fashion than 
similar routines built into TOS, and allow programs written for the UNTX operating 
system or for MS-DOS to be compiled and run under TOS with minimal alteration. 


For more information, see the Lexicon entry on UNIX rontines. 


The AES and VDI libraries 


AES and YDI are elements in the GEM (graphies environment management) system, 
Together, they give the user a convenient way to interact with the computer through 
graphics images. 


VDI stands for virtual device interface, It consists of a set of basic graphics routines 
that draw lines, polygons, circles, and ellipses; plus routines that allow your program 
to receive information from the user, plus a set of text fonts and device drivers, 


‘The VDI allows programmers to create graphics images that can be displayed on any 
of & number of devices, including the screen, printer, tablet, plotter, video slide 
camera, and others. 


In addition, the VDI allows you to write metafiles, which hold the logical description 
of a graphics image, An image stored in this manner can be manipulated easily by the 
user, which enhances the interactive powers of the GEM system. 


AES stands for application environment system. In effect, the AES combines elements 
of the disk operating system and of the VDI to create a graphics-oriented environ 
‘ment for the user. The AES governs the tunning of processes, or applications, on the 
Atari ST; it also controls the running of menus and windows on the GEM desktop. 


To programmers, AES routines give a way to use windows, menus, graphics objects, 
Gislogues, and the other pre-defined elements of the graphics environment. 


The AES and VDI routines themselves live in the Atari ROM BIOS. Calls to them are 
Kept in two libraries: libaes.a and libvdl.a, respectively, Bindings that declare these 
routines in the C manner are kept in the header files aesbind.h and ydibind.h. Three 
SUditional header files are also included to help you create programs, as follows: gem- 
defs-h includes a number of mnemonic definitions, and declares some structures used 
in VDI programs; obdefs.h declares structures used to create graphics objects; and 
Portab-h defines terms used in the DRI dialect of C. 
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Compiling programs that use AES and VDI 


To compile a program with AES or VDI routines, use the -VGEM option on the ce 
command line. For exemple, if the program sample. has AES routines in it, you can 
compile it with the following command: 


ce “GEM sanple.e 


Every AES and VDI routine, header file, and archive is described in the Lexicon. If 

‘ou are not sure where to begin, First look up the individual entries for AES and VDI, 
Each gives more information about how these tools work; each also contains a list and 
brief summary of each of its library routines. Separate articles also have been written 
to describe windows, menus, graphics objects, and metafites, These entries describe in 
detail how to use these specialized graphics forms. The entries for the individual 
library routines also contain numerous examples. Each example is a complete C 
program that can be compiled and run, and demonstrates some aspect of the 
AES/VDI environment. These examples are a good place to begin your study of 
AES/VDI. 


The Line A library 


Line A is the interface to the Atari ST's assembly-language-level graphics routines, 
Its name refers to the fact that its opcodes all begin with the hexadecimal number ‘A* 
(OxA). 


Each Line A function consists of few lines of assembly language, which save registers, 
load parameters, execute one of the unimplemented Line A’ instructions, restore 
Tegistert,and yefurn; ‘These'perform aiinple graphics functians ichas déswing Dneed 
displaying characters, or drawing polygons, The GEM VDI routines use Line A to do 
their work. 


Most Line A functions pass their parameters through an external structure, rather 
than through arguments passed in the usual manner, The exceptions are linea, which 
uses a specialized structure to copy and move portions of the screen (also called “blit- 
ting"); lineac, which takes a pointer; and linead, which takes two pointers. All 
functions and structures are declared in the header file linea.h. 


‘The entry on Line A in the Lexicon contains more information, and includes two 
sample programs. 


30 Mark Williams C 


Tutorial Introduction 


Debugging Programs with Mark Williams C 


Mark Williams C comes with several utilities that help you debug your programs. 
These include db, which is a powerful symbolic debugger; nm, which prints symbol 
ables from programs, for analysis; and od, which will print an octal dump of a file 


db: the debugger 


Mark Williams C includes a symbolic debugger to assist you with debugging your 
programs. db can work with a compiled program, and includes a number of com- 
Inands that allow you to examine just what your program is doing during its execu- 
tion, 

To sce what db can do, compile the program hello.c, which you created earlier in this 
tutorial, by entering the following command: 


nel 


.. step through the following script. db’s commands are in boldface in the left~ 
column; the right-hand column gives a brief description of what each command 


db hello.pre invoke debugger 
printt:b set tracepoint on printf 
display all breakpoints 
run program 

do traceback 

look at the registers 


printt,202% symbolically disassemble 20 instructions 
te continue execution 
p display breakpoints; none shown as program is over 


quit db 


As you can see, db allows you to set breakpoints, run through the program, and ex- 
antine what it does in a variety of manners, For a fuller introduction db, and instruc— 
Uons an how so use it to debug your programs, sec the entry for db in the Lexicon, 


od: octal or hexadecimal dump 


od prints outa file in octal machine words, If you type od without an argument, it 
accepts what you type at the keyboard as input; when you type a <ctrl-Z> and car- 

ge return, it then returns what you typed in octal. Normally, you give od a file 
name as an argument; to display an octal Gump of the file temptile, type 
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od tenpfite 


‘od can also display files in hexadecimal or decimal, and in bytes or words, whichever 
you prefer, 


num: print symbol tables 


um prints out the symbol table from an object module or library. Tt is designed to 
work with libraries created by with the archiver ar, and with object modules cam- 
piled with Mark Williams C. 


By default, nm only prints symbols with a C-style format. To use for the library 
libe.a, simply type 
rm a:\LiB\Libe.s 


For more information on using these debugging tools, see their entries in the Lexicon, 


Selected References 


‘The following list names books that you may find helpful in developing your skills 
with C. This list is by 0 means exhaustive; however, it should prove helpful to both 
beginners and experienced programmers. 


American National Standards Institute: Draft Programming Language C (May 1986 
Drajt). Washington, D.C: X3 Secretariat, Computer and Business Equipment 
‘Manufacturers Association, 1986. 


AT&T Bell Laboratories: The C Programmer's Handbook, Englewood Cliffs, N.J.: 
Prentice-Hall Inc, 1985. 


Chirlin, P.M. Introduction to C. Beaverton, Or: Matrix Publishers Inc., 1984, 
Derman, B. (ed.): Applied C. New York: Van Nostrand Reinhold Co. Inc., 1986, 
Feuer, AR: The C Puzzle Book. Englewood Cliffs, N.J;; Prentice-Hall Inc., 1982. 


Gehani, G.: Advanced C: Food for the Educated Palate. Rockville, Md.; Computer 
Science Press, 1985. 


Hancock, L., Krieger, M.: The C Primer. New York: McGraw-Hill Book Publishers 
Ine., 1982. 


Hogan, T The C Programmer's Handbook. Bowie, Md.; Brady Publishing, 1984, 


Kernighan, B.W., Ritchie, D.M: The C Programming Language. Englewood Cliffs, 
N.J.: Prentice-Hall Inc., 1978, 
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Kernighan, B.W., Plauger, PJ: The Elements of Programming Style, ed. 2, New 
York: McGraw-Hill Book Co,, 1978. 

Kochan, SG: Programming in C. Hasbrouck Heights, N.Jz Hayden Book Co. Inc., 
1983 


Knuth, DE: The Art of Computer Programming, vol. 1: Basic Algorithms. Reading, 
Ma; Addison-Wesley Publishing Co,, 1969. 


Knuth, DE: The Art of Computer Programming, vol. 
Reading, Ma: Addison-Wesley Publishing Co., 1969, 


Knuth, DE: The Art of Computer Programming, vol. 3: Sorting and Searching, 
Reading, Maz Addison-Wesley Publishing Co, 1968. 


Plum, T Learning to Program in C. Cardiff, NJ Plum Hall Inc., 1983. 
Plum, Ty C Programming Guidelines, Cardiff, NJ: Plum Hall Inc., 1984, 
Que Corp., 1983. 


Purdum, J., Lestie, T.C., Stegemoller, A.L: C Programmer's Library. Indianapolis; 
Que Corp., 1984. 


Traister, RJ: Programming in C for the Microprocessor User. Englewood Cliffs, 
NJ: Prentice-Hall Inc., 1984, 


Tysister, R.Jz Going from BASIC to C. Englewood Cliffs, N.J: Prentice-Hall Inc. 
1984 


: Seminumerical Algorithms. 


Purdum, J: C Programming Guide. Indianapolis 


Naite, May Prata, S., Martin, Dz C Primer Plus. Indianapolis: Howard W. Sams The, 
1984 


Weber Systems, Ines C Language User's Handbook. New York: Ballantine Books, 
4 


Zahn, C.T; C Notes. New York: Yourdan Press, 1979, 


Atari ST information 


tae P., Fitler, W: Programmer's Guide to GEM. Berkeley, Calif: SYBEX, Inc. 


Digital Research Institute: GEM Programmer's Guide. Pacific Grove, C: 
Research Institute, Inc., 1984, 


General Instrument Corporation: Programmable Sound Generator Data Manual, 
Hicksville, N,Y.: General Instrument Corporation, 1981. 


Gerits, K., Englisch, L., Bruckmann, Ri Atari ST Internals: The Authoritative 
‘sider's Guide. Grand Rapids, Mich: ABACUS Software, Inc., 1986. 


Digital 
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§M68000 16/32-Bit Microprocessor Programmer's Reference Manual, ed. 4, 


Englewood Cliffs, N.J.: Prentice-Hall, Inc., 1984, 


Oren, T Professional GEM, Available through CompuServe, ANTIC-ONLINE, 
Atari ST forum, Highly recommended. 


Szczepanowski, N., Gunther, B: Atari ST GEM Programmer's Reference. Grand 
Rapids, Mich.: ABACUS Software, Inc., 1986. 
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2, Error messages 


‘This cheptet lists all of the error messages that the compiler, the assembler as, and the 
linker Id can produce, 


“The messages are in alphabetical order, and are marked whether they come from the 

compiler, the essembler, er the linker. Those from the compiler are marked by the 
compilation phase, and whether it indicates a fatal, error, strict, or warning condi- 
tion, The compilation phases are epp, the preprocessor; ec, the parser; cc1, the code 
generator; ce2, the optimizer; and cc3, the disassembler, 


A fatal message usually indicates a condition that caused the compiler to terminate 
execution; fatal errors from the later phases of compilation often cannot be fixed by 
the user, and most likely indicate problems ia the compiler itself. 


An error message refers to a condition in the source cade, such as unbalanced braces, 
that caused compilation to cease. 


Warning messages point out code that is compilable, but may produce trouble when 
the program is executed. A strict message refers to a passage in the code that is unor- 
thodox and may not be transportable, 


Each error message is followed by a brief description and explanation, 


(as, error) 
Dot label exror. This indicates that a period was used asa label, €.g.," 


a (as, error) 
Addressing error. This is generated by nearly any kind of operand/instrution 
mismatch or semantic error in address fields. 

address wraparound (Id, fatal) 


A segment of the program has exceeded the size allowed by the microproces- 
sor’s architecture. 


ambiguous reference to “siring™ (ec0, error) 
string is defined as a member of more than one struct or union, and is 
seferenced via a pointer to one of those structs or unions, and there is more 
than one offset that could be assigned. 


argument list has incorrect syntax (cc0, error) 
‘The argument list of a function declaration contains something other than a 
comma-separated list of formal parameters. 


Srray bound must be a constant (ce0, error) 
An array size has been declared witha variable or undefined size. 


array bound must be positive (ce0, error) 
An array was declared to have a negative size, 
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array bound too large (¢e0, error) 
The array is too large to be compiled with 16-bit index arithmetic. The 
programmer should devise a way to divide the array into compilable portions, 
or rethink the approach to handling these data. 


array row has 0 length (ec0, error) 
‘An array was declared to be zero units long, or some dimension of the array 
other than the first was made to be flexible. 
associative expression too complex (cel, Fatal) 
‘An expression involving associative binary operators, such as 
}1+i2413+...+130;, has too many operators. Simplify the expression. 


bad argument storage class (c¢0, error) 
‘An argument was assigned a storage class that the compiler does not recognize. 
‘The only valid storage class is register. 

bad external storage class (ec0, error) 
‘An extern has been declared with an invalid storage class, e.g. register or 
auto. 

bad field width (ce0, error) 
‘A field width was declared to be negative or greater than will fit into the ob- 
ject holding it 

bad filler field width (ce0, error) 
‘A filler field width was declared to be negative or greater than will fit into 
the object holding i 


win 


bad flexible array declaration (cc0, error) 
Flexible arrays have missing array bounds, e. 
baddisk:disk error (Id, fatal) 
Id either cannot read or cannot write to the mass-storage device. Check the 
disk you are using fo see that it is working correctly. 


break not in a loop (eet, error) 
‘A break occurs that is not inside s loop or a switch statement, 


, char *argyll 


call of non function (ec, error) 
‘What the progrem attempted to call is not a function. 


cannot add pointers (ce0, error) 
‘The program attempted to add two pointers. infs may be added to or sub- 
tracted from pointers, and two pointers to the same type may be subtracted, 
but no other arithmetic operations are legal on pointers. 


cannot apply unary ‘&' to a bit field (e¢0, error) : 
The program attempted to use the address of a bit within a byte, which is 
illegal; only bytes can be addressed, not the bits within them. 
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cannot apply unary “& to a register variable (ec0, error) 
Because register variables are stored within registers, they do not have addres~ 
ses, which means that the unary & operator cannot be used with them. 


cannot cast double to pointer (ce0, error) 
‘The program attempted to cast a double to a pointer. 


cannot cast pointer to double (ec0, error) 
‘The program attempted to cast a pointer to a double. 


cannot cast structure or union (e¢0, error) 
‘The program attempted fo cast a struct or a union, 


cannot cast to structure or union (ec0, error) 
‘The program atempted to cast a variable to a union or struct, 

4: cannot create (as, error) 
‘The assembler as cannot create the output file it was requested to create. This 
often is due toa problem with the output device; check and make sure that it 
is working correctly and not full, 


string: cannot create (epp, fatal) 
“The preprocessor epp cannot create the output file siring that it was asked to 
oteate. This often is due to a problem with the output device; check and make 
sure that it is working correctly and is not full. 


L create string (Id, Fatel) 
The linker ld cannot create the output file it was requested to create, ‘This of- 
ten is due to a problem with the output device; check and make sure that it is 
working correctly and is not full 

cannot declare array of functions (ce0, error) 

extern int (*f11)Q; declares F to he an array of pointers to functions that return 

ints. Arrays of Functions are illegal. 


cannot declare flexible automatic array (ce0, error) 
The program does not explicitly declare the number of elements in an 
automatic array 

cannot initialize fields (ce0, error) 
The program attempted to init 
supported, 


e hit fields within a structure. This is not 


cannot initialize unions (ced, error) 
The program attempted to initialize a union within its declaration, unions 
cannot be initialized. 

string: cannot open (ep, fatal) 
The preprocessor epp cannot open the file string of source code that it was 
asked to read, epp may not have been correctly told the directory in which 


Mark Williams C 37 


Mark Williams C for the Atari ST 


this file is to be found; check that the file is located correctly. 


cannot open include file string (ep, error) 
‘The program asked for file string, that was not found in the same directory 
the source file, nor in the default include directory specified by the environ 
mental variable INCDIR, nor in any of the directories named in -I optios 
given to the ce command, 


sannot open string (seg aumber) (Ad, Fatal) 
‘The linker Id cannot open the object module that it was asked to read. Mal 
sure that the storage device is working correctly, and that Id has been giv 
the correct names of the file and of the directory in which it is stored. 


string: cannot reopen (ce2, fatal) 
‘The optimizer ec2 cannot reopen a file that it has been working with. Mal 
sure that your mass storage device is working correctly and that it is not full. 


‘can’t open libstring.a (Id, fatal) 
The linker Id cannot open a library that it has been asked to link ino yot 
program. Make sure that you named the library correctly and that the e1 
vironmental parameter LIBPATH is set correctly if you used the -1 option 
the ce command line. 


can't open séring (Id, fatal) 
The linker Id cannot open a file that it has been asked to work with. Mak 
sure that your mass storage device is working correctly, and that Id has bel 
given the correct names of the file and of the directory in which it is stored, 


can't open temp file (Id, fatal) 
The linker Id cannot open the temporary file created by the compiler or 
assembler, Make sure that your mass storage device is working correcily, 2 
that Id has been given the correct names of the file and of the directory i 
which it is stored. 


can't read strimtg (Id, fatal) 
The linker Id cannot read the file named. Make sure that your mass storage 
device is working correctly, and that Id has been given the correct nemes of 
the file and of the directory in which it is stored, 


case not in a switch (ce0, error) 
‘The program uses a ease label outside of a switch statement. 
class not allowed in structure body (ce0, error) 
A storage class such as register or auto was specified within a structure, 
compound statement required (c¢0, error) 4 
A construction that requires a compound statement, €g., a function definitio 
array initialization, or switch statement, does not have one. 
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nt expression required (ce0, error) 
‘The program uses a variable in a statement that requires a constant expression, 


consta! 


constant “number” promoted to long (cc, warning) 
The compiler promoted a constant in your program to long; although this is 
at strictly illegal, it may create problems when you attempt to port your code 
to another system, especially if the constant appears in an argument list 
constant used in truth context (ce0, strict) 
4 conditional expression for an if, while, or for statement has turned out to be 
always true or always false 


construction not in Kernighan and Ritchie (eed, strict) 


This construction is not found in The C Programming Language; although it 
can be compiled by Mark Williams C, it may not be portable to another com- 
piter, 


continue aot in a loop (ce0, error) 
The program uses 4 continue statement that is not inside a loop. 


#define argument mismatch (cpp, warning) 
The definition of an argument in a #define statement does not match its sub- 
sequent use, One or the other should be changed. 


declarator syntax (ce, error) : 
‘Tne program used incorrect syntax ina declaration, 


rault lebel not ina switeh (ec0, error) 
The program used 2 default label outside a switch construct. 


disk error (Id, fatal) 
The linker 1d encountered @ problem with the storage device when it at- 
tempted to read or write a file. Check that the disk is working correctly; if ld 
ig working with a floppy disk, make sure that the disk is sound and that it is 
not write-protected, 


divide by 2ero (ce0, warning) 
‘The program will divide by zero if the code just parsed is executed. Although 
the program can be parsed, this statement may create trouble if executed. 


dupli 


ced ease constant (ee0, error) 
A case value may appear only once in a switch statement, 
else used without #if or #ifdef (ep, error) 

“The program has an #else without a preceding #if, Most likely, an extra #else 
‘was inserted, or an #if or #ifdef was overlooked. 


'y Switch (ce0, warning) 
A switch statement has no case labels and no default labels. 
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Hendif used without #if or #ifdef (cpp, error) 
The program has an #endif without a preceding +f. 


EOF in comment (epp, error) 
An EOF appears in @ comment. The file of source code may have been trun= 
cated, or you failed to close a comment; make sure that each open-commel 
symbol “/*" is balanced with a close-comment symbol “*/" 

EOF in macro argument (epp, warning) 

An EOF appears in a macro argument. 


error in #define syntax (cpp, error) 
‘The syntax of a #define statement is incorrect. 


error in enumeration list syntax (¢c0, error) 
‘The syntax of an enumeration declaration contains an error. 


error in expression syntax (¢c0, error) 
‘The parser expected to see a valid expression, but did not. 


error in #include syntax (epp, error) 
An #include directive must be followed by a string enclosed by either quota= 
tion marks ("") or angle brackets (<>). 


expression too complex (cel, fatal) 
‘The code generator cannot generate code for an expression. Simplify your 
code. 


external syntax (ceO, error) 
This could be one of several errors, most often a missing ‘(, 


file ends within a comment (ec0, error) 
The source file ended in the middle of a comment, If the program uses nested 
comments, it may have mismatched numbers of begin-comment and end- 
comment markers. If not, the program began a comment and did not end it, 
perhaps inadvertently when dividing by *something, e.g., a=b/*ed;, 

function cannot return a function (ec0, error) 
‘The function is declared to return to another function. A function, however, 
can return a pointer to a function, as does int (*signal(n, ))(). 

function cannot return an array (ee0, error) 
‘A function is declared to returnan array. A function can return a pointer to a 
structure or array, 


functions cannot be parameters (ec0, ertor) 


‘The program declares a function as a parameter, ¢., int q(); x(q)s- 


identifier “string” is being redeclared (ec0, error) 
The program declares variable string to be of twa different types, This often 
may be due to an implicit declaration, the use of a function before a subse~ 
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quent declaration, Check for name conflicts. 


identifier “siring™ is not a label (ec0, error) 
The program attempts to goto a nonexistent identifier. 


identifier “string” is not a parameter (¢c0, error) 
The variable “string” did not appear in the parameter list, 


identifier “siring” is not defined (ce0, error) 
The program uses identifier string but does not define it. 


identifier “string” not usable (ee0, error) 
string is probably a member of a structure or union wi 
an expression. 

illegal character constant (c¢0, error) 

Lagal character constants consist of a single letter, a backslash ‘\' followed by 
one of \, n, t, b, rf, ¥, or a, or @ backslash followed by up to three cctal 
digits. 

illegal character (number decimal) (ec0, error) 

‘A control character was embedded within the source code. number is the 
decimal value of the character. 


appears by itself in 


illegal + construct (ce0, error) 

The parser recognizes control lines of the form #line_number (decimal) or 

#file_name. Anything else is illegal. 

itlegal control line (epp, error) 
A ‘#' is followed by a word that the compiler does not recognize. 


illegal label “séring” (ee0, error) 
‘The program uses the keyword string as a goto label. Remember that each 


label must end witha colon. 


illegal operation on “void” type (ce, error) 
‘The program tried to manipulate a value returned by a function that had been 
declared to be of type ¥ 


gal structure assignment (ce0, error) 
‘The structures have different sizes. 

illegal subtraction of pointers (cc0, error) 

A pointer can be subtracted from another pointer only if both point to objects 
of the same size, 

illegal use of a pointer (ec0, error) 

A pointer was used illegally, e.g., multiplied, divided, or anded. You may get 
the result you want if you cast the pointer toa long. 
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‘legal use of a structure or union (ec0, error) 
‘You may take the address of @ struct, access one of its members, assign it 
another structure, pass it as an argument, and return. All else is illegal. 

illegal use of floating point (ce0, error) 

‘A float was used illegally, e.g., in a bit-field structure, 
illegal use of “void type (ce0, error) 


The program used void creatively, Strictly, there are only void functios 
‘Mark Williams C also supports the cast to void of a function call 


‘illegal use of void type in cast (ec0, error) 

‘The program uses a pointer where it should be using a variable, 
string in #i€ (cpp, error) 

‘A syntax error occurred in a #if declaration. siring describes the error i 


detail 


inappropriate “alien” modifier (cc0, error) 
The alien type is used to interface C with non-C functions; your prog: 
tried to use alien as an internal function rather than as a reference to an ex= 
ternal function. 


inappropriate “ong” (ec0, error) 
Your program used the type long inappropriately, 2. 


inappropriate “short" (cc0, error) 
‘Your program used the type short inappropriately, ¢.g,, to describe a char. 


inappropriate “unsigned” (ce0, error) 
‘Your program used the type unsigned inappropriately, ©. 
double. 


indirection through non pointer (ce0, error) 
‘The program attempted io use a scalar as a pointer; you must first cast it to @ 
pointer to something. 


initializer too complex (ce0, error) 
‘An initializer was too complex to be calculated at compile time, You should 
simplify the initializer to correct this problem. 


integer pointer comparison (ec, strict) 
‘The program compares an integer with 2 pointer without casting one to the 
type of the other. While this is legal, the comparison may not_work on 
machines with non-integer pointers, e.g., segmented Z8000 or LARGE-model 
18086, or on machines with pointers larger than ints, e.g., the 68000. 


integer pointer pun (cc0, strict) ‘ 
“The program assigns a pointer fo an integer, or vice versa, without casting the 
right-hand side of the assignment to the type of the left-hand side, While this 


. to describe a char. 


, to desoribe a 
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js permitted, it is often an error if the integer has less precision than the 
pointer does. Make sure that any functions called in the expression that 
return pointers are properly declared, 


raul compiler error (ce0, cel, c¢2, cc3, fatal) 
The program produced a state that should not happen during compilation 
Forward a copy of the program, preferably on a machine-readable medium, to 
Mark Williams Company, together with the version number of the compiler, 
the command line used to compile the program, and the system configuration, 
For immediate advice during business hours, telephone Mark Williams Com- 
pany 


Invernal error, c=number in expr. (as, error) 
Internal problem; contact Mark Williams Company. 


inte! 


“seriag™ 18 enum tag (ee0, error) 


ing” isa struct tag (c€0, error) 


is union tag (ee0, error) 
string has been previously declared as a tag name for a struct, union, or enum, 
and is now being declared as another tag. Perhaps the structure declarations 
have been included twice. 


“string! 


is nova tag (ce0, error) 
A struct or union with tag string is referenced before any such struct or union 
isdeclared. Check your declarations against the reference. 


“string” is not @ typedef name (cc, error) 
string was found ina declaration in the position in which the base type of the 
declaration should have appeared. string is not one of the predefined types or 
a typedef name. 

“string” is not an “enum” tag (ce, error) 

An enum with tag sfring is referenced before any such enum has been 
declared, 

class “string” (number) is not used (¢c0, strict) 

Space was allocated for the variable string of the given class by the declera~ 
tion on Tine tiuntber, but it was not used. 

“siring” undefined (¢e0, error) A 

The program does not declare the label string, but it is referenced in a goto 
statement, 


left side of “string” not usable (ce0, error) 
The left side of string should be a pointer, but is not, 


value required (ce0, error) 
‘The left-hand value of a declaration is missing or incorrect. 
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m (as, error) 
‘Multiple definition, The offending line is involved in the multiple definitic 
of a label, 


macro body too long (epp, fatal) 
The size of the macro in question exceeds 200 bytes, which is the limi 
designed into the preprocessor, Try to shorten or split the macro. 


macro expansion overflow (epp, fatal) 
‘The program contains a macro extension that exceeds the allowed limit of 2( 
bytes. 


macro string redefined (epp, warning) 
‘The program redefined the macro string. 


macro string requires arguments (epp, error) 
‘The macro calls for arguments that the program has not supplied. 


macros nested number deep, loop likely (epp, error) 
Macros call each other number times. You would be well advised to simplify 
the program. 


member “séring" is not addressable (ce0, error) 
The array string has exceeded the machine's addressing capability. Structure 
members are addressed with 16-bit signed offsets on most machines. 


member “string” is not defined (ce0, error) 
‘The programs references a structure member that has not been declared, 


mismatched conditions! (ce0, error) 
In a‘?'-" expression, the colon and all three expressions must be present. 


misplaced *:" operator (cel, error) 
‘The program used a colon without a preceding question mark. It may be a 
misplaced label, 


missing “=" (cc0, warning) 
‘An equal sign is missing from the initialization of a variable declaration, Note 
that this is a warning, not an error: this allows Mark Williams C to compile. 
programs with “old style” initializers, such as int 1 1; however, use of this fea- 
tuse is strongly discouraged. 


missing “:" (cc, error) 
‘A colon’ is missing after a case label, a default label, or a ‘7" in a *?'—""' con~ 
struction, 


missing “," (cc0, error) 


A’comma is missing from an enumeration member list, 
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snissing “1” (ee0, error) 
A left brace ‘{’ is missing after a struct tag, union fag, or enum tag in a 
definition. 

missing “(” (ceO, error) 
The if, while, for, and switch keywords must be followed by parenthesized 
expressions 


missing “| (ce0, error) 
A right brace ')' is missing from a struct, union, or defi 
itialization, or from a compound statement. 


jon, from an in- 


1" (ec0, error) 
‘A right bracket *[! is missing from an array declaration, or from an array 
reference, 


missing 


(cc0, error) 


missing 
‘A right parenthesis ‘) is missing anywhere after a left parenthesis “( 


missing 7" (ec0, error) 
‘A semicolon +’ does not appear after an external data definition or declara~ 


tion, after a struct or union member declaration, after an automatic data dec 
laration or definition, after a statement, or in a for(;:) statement. 


missing “while” (ce0, error) 
A while command does not appear after a do in a do-while() statement, 


missing #endif (epp, error) 
An #if, #ifdef, or #ifadef statement was not closed with an #endif statement. 


missing label name in goto (cc0, error) 
A goto statement does not have a label. 

missing member (ce0, error) 
A‘? or “=>” is not followed by a member name. 

missing output file (cpp, fatal) 
The preprocessor epp found a -o option that was not followed by a file name 
for the output file. 

missing right brace (cc0, error) 
‘A right brace is missing at end of file. The missing brace probably precedes 
lines with errors reported earlier. 


missing “string” (ee0, error) 


The parser ec expects to see token string, but sees something else. 


missing semicolon (ec0, error) 
External declarations should continue with ," or end with ‘7. 
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missing type in structure body (cc0, error) 
‘A structure member declaration has no type. 
multiple classes (cc0, error) 


‘An element hes been asigned to more than one storage class, ¢.8, exten 
register. 


multiple #else's (cpp, warning) 
‘An #ifdef, #if, or #ifndef statement is followed by more than one #el 
statement. 


multiple types (cc0, error) 
‘An element has been assigned more than one data type, €.8., 


nested comment (epp, warning) 
By default, Merk Williams C does not accept nested comments. To tell 
Williams C to accept nested comments in your program, use the opi 
-YCNEST on your ce command line. 


feger float, 


newline in macro argument (ep, warning) 
‘A macro argument contains newline character, 


no input found (Id, fatal) 
‘The Id command line names no object or archive files to link 
nonterminated string or character constant (ce0, error) 
‘A line that contains single or double quotation marks left off the closi 
quotation mark. A newline in a string constant may be escaped with ‘\’ 
number has too many digits (cc0, error) 
‘A number is too big to fit into its type. 
0 (as, error) . 
‘An unrecognized opcode mnemonic was found. Contrast this with error ‘a’, 
where the opcode is recognized but the syntax line is in error. 


only one default label allowed (ec0, error) 
‘The program uses more than one default label in a switch, 
out of space (Id, Fatal) 
‘malloc could not allocate adequate space in memory for the linker Id to work. 
out of space (fBeppfR, ec0, ect, ec2, cei, fatal) 
‘The compiler ran out of space while attempting to compile the program. To 
remove this error, examine your source and break up any functions that 
extraordinarily large. 
out of tree space (¢c0, fatal) 


The compiler’allows a program to use up to 350 tree nodes; the program ex- 
ceeded that allowance. 
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qutdated ranlib (Id, warning) 
“The date stamp on the library file is younger than that in the ranlib header. Tf 
the library has been altered, the ranlib can be updated with the archiver ar; 
“ee the Lexicon entry on ar fo see how this is done. If the library has not been 
altered, this message may be due to an installation error, see the Lexicon entry 
on ranlib for more information, 
pas, error) : 
Phase error. The value of @ label changed during the assembly, An instrue- 
tion has a size that differs between the first and second passes 
entially nonportable structure access (cc), strict) 
‘A program that uses this construction may not be portable to another com- 
cor assertion failure (epp, warning) 
‘A #ussert directive that Was tested by the preprocessor epp was found to be 
fale 


pot 


prepro: 


(as, error) 
‘Questionable syntax. The assembler has no idea how to parse this line, and it 


# given up. 
(as, error) 
Relocation error. The program attempted to create or use an expression in @ 
way that the linker cannot resolve, 


return type/function type mismatch (c¢0, error) 
What the function was declared to return and what it actually returns do not 
match, and cannot be made to match 


return(s) illegal in void function (cc0, error) 
A function that wat declared to be type void has nevertheless attempted to 
relurn a value. Either the declaration or the Function should be altered. 


risky type in truth context (¢c0, strict) 
The program uses a variable declared to be a pointer, long, unsigned long, 
float, or double as the condition expression in an if, while, do, or ‘P-'". This 
could be misinterpreted by some C compilers. 


5 (as, error) 
Segment error, The program attempted to initialize something in a segment 
that contains only uninitialized data, 

Size af sttuct “string” is not known (ec0, error) 

size of union “string” is not known (ce0, error) r 
‘A pointer to a struct or union is being incremented, decremented, or subjected 
to array arithmetic, but the struct or ualon has not been defined. 
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size of string too large (ce0, error) 
‘The program declared an array or struct that is too big to be addressable, e.g, 
Jong a{20000]; on a machine that has a 64-kilobyte limit on data size at 
four-byte longs. 
sizeof(string) set to number (ce0, warning) 
‘The program attempts to set the value of string by applying sizeof to a fun 
tion or an extern; the compiler in this instance has set string to number. 
storage class not allowed in cast (cc0, error) 
‘The program casts an item as a register, static, or other storage class. 


structure “siring” does not contain member “mi” (¢c0, error) 
‘The program attempted to address the variable string.m, which is not defines 
a part of the structure string 
structure or union used in truth context (ec0, error) 
‘The program uses a structure in en if, while, or for, or 
switch of non integer (ec0, error) 
‘The expression in a switch statement is not type int or char, You should ca: 
the switch expression to an int if the loss of precision is not critical. 


switch overflow (cel, fatal) 
‘The program has more than ten nested switches, 


statement, 


too many adjectives (ce0, error) 
A variable’s type was described with too many of long, short, or unsigned. 


too many arguments (cc0, fatal) 
‘No function may have more than 30 arguments, 


too many arguments in a macro (epp, fatal) 
“The program uses more than ‘ten arguments with a macro, 


too many cases (cel, fatal) 
‘The program cannot allocate space to build a switch statement, 


too many directories in include list (epp, fatal) 
‘The program uses more than ten #include directories, 
too many initializers (ee0, error) 
The program has more initializers than the space allocated can hold. 


too many structure initializers (ee0, error) 
The program contains a structure initialization that has more values than” 
members. 


trailing “," in initialization list (ce0, warning) 
An initialization statement ends with a comma, which is Jegal. 
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Error messages 


pe clask (e€0, €r700) 
‘The parser expected to find matching types but did not. For example. the 
types of ef and e2 in (x) ? el: e2 must either both be pointers or neither be 
pointers. 
2 required in cast (ce0, error) 

‘The tyne is missing from a cast declaration. 


typ 


wlasersor) . 
(as, e1 0symbol is used but never defined. The symbol's name is displayed 

unexpevted end of enumeration list (ec0, error) 
‘An end-of-file flag or a right brace occurred in the middle of the list of 
enumerators, 

uncapested EOF (cc0, ect, ce2, ce3, Fatal) 
EOF occurred in the middie of a statement, The temporary file may have 
been corrupted or truncated by an earlier phase. 

union “siring” does not contain member m (ec0, error) 
‘The program attempted to address the variable string m, which is not defined 
as part of the structure string. 

string: unknown option (epp, fatal) 
‘The preprocessor epp does not recognize the option string. Try re-typing the 
ee command line. 

zero modulus (ce0, warning) 
The program will perform a modulo operation by zero if the code just parsed 
is executed. Although the program can be parsed, this statement may create 
trouble if executed. 
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3. The Lexicon 


The rest of this manual consists of the Lexicon. The Lexicon consists of more 
700 articles, each of which describes a function or command, defines 2 ter 
otherwise gives you useful information. The articles are organized in alphabetical 
der, to ensure that everything is easy to find. 


The following page gives a sample article in the Lexicon format. For more inf 
tion on how to use die Lexicon and how it is organized, see the entry in the Lexi 
on Lexicon. 
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example 


example-Sample entry 
‘Give an example of Mark Williams Lexicon format 
Tong example( foo, bar) int foo; long bars 
This is an example of the Mark Williams Lexicon format of software documen- 
tation. At this point, each entry has a brief narration that discusses the topic in 
deta 
‘The line in boldface above gives the usage of the function being described. ‘The 
imaginary function is called example, long means that it returns a long; if no 
type is given, then assume that it returns an int; and if the function should 
return nothing, it will be given as type vold. foo and tar are example's ar- 
guments; foo must be declared as an int, and bar as a long. 
exemple 
aire) € 

printf(rmany srticles have an exenple.\9"3; 

3 
See Also 
all other related topics and functions 
Notes 
If technical terms are used that you do not entirely understand, look them up in 
the Lexicon. In this way, you will gain a secure understanding of how to use 
Mark Williams C. 
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abort—General function (libe.a/abort) 
End program immediately 
abort() 


abort terminates a process and prints @ message on the screen. Tt is aormally 
voked in situations in a program that “should not happen”. The terminati 
carried out bya call to exit, with a non-zero exit status. 


See Also 
exit, exit 


Diagnostics 
abort prints the relative address from the beginning of the program, so that 
can look the location up in the symbol table. See the entry for nm for more 
formation on how to extract the symbol table from an executable program. 


‘abs—General function (libe.a/abe) 
Return the absolute value of an integer 
abs(n) int 1; 


abs returns the absolute value of integer 7. 
Example 


maine 
fxtern char *gets¢); 
cxtern int stoi; 
char stringiS4l; 
int input? 
for Gi) 
rinef(venter an inteser 
ittgerscstring)) € 
input = atoidstring); 
printt(sbs(id) is 3a.\n", input, absCinput)) 


™: 


> 
flee break: 
> 
1 
See Also 
fabs, floor, int 


Notes 
On two's complement machines, the abs of the most negative integer is itself. 
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seston 


acos 


Mathematics funetion (Iibm.a/acos) 


scot Cojoulate inverse cosine 
include <math.h> 
double acos(arg) double ar 
‘cos calculates inverse cosine. arg should be in the range of [-1., 
‘will be in the range [0, PI]. 
Example 
This example demonstrates the mathematics func' 
cabs, co8, hypot, sin, and tan, 
finetude <math.h 
dodispiay(vatue, nana) 
egbie value; char *nane; 
if certo 
perrar(naney; 
tse 
printécuxig Ze\n", value, rane): 
> 
feetine dieplay(x) dodispley¢édoubley(ad, "ed 
sain) € 
extern char *92t30)7 
suble 7 
char stringtéel 
forts € 
prinef(venter punbers "9; 
Hregerscatting) == 9) 
break; 
x = atot(string); 
Sispleyds 
ispleyteoeex); 
atspley(sing); 
aisplay(eanto 
aisplaytaces(2080009)5 
aisptayesinesinod) 
aisplay(atanctenOo)); 
ieplay(aten2(sin(x) ,c0860)92 
aispley(hypor(sinex) £0800) 
aisplay(eabscsin(x) ,c08G) 
> 
> 
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1.j; the result 


ns aces, asin, atan, atan2, 


53 


address-AES ___ Lexie 


See Also 
errno, errno.h, mathematics Ubrary, perror 


Diagnostics 
(Out-of-range arguments set errno to EDOM and return 0. 


adress—Definition j 
‘An address is the location where an item of data is stored in memor 
dress on the 68000 is simply a 24-bit integer that is stored as a 32-bit ini 
(On the 68000, the upper eight bits are ignored; this is not true with more 
vanced microprocessors in this family, such as the 68020, On machines wif 
memory-mapped I/O, such as the 68000, some addresses may be used to contre 
or communicate with peripheral devices. Thus, using an incorrect address as ap 
argument to poke may accidentally disable a peripheral device. 


See Also 
peekb, peekl, peekw, pokeb, pokel, pokew 


often, 


AES consists of the following elements: a kernel, a screen manager, buffers, a 
a set of “libraries”. Each is briefly described below. 


‘The kernel performs rudimentary 1/O and provides limited, multi-tas 
capability, It manipulates concurrently executing routines, or “processes” 
the following manner. When a process has executed 1v te point where it ma 

2 request from the Kernel, it's placed on a “not ready” list, where it sleep 
When a “event” occurs that the program is awaiting (that is, when the usee 
manipulates the mouse or types on the Keyboard, when the system's timer si 
nals that @ certain amount of time has elapsed, or when a message is received 
from another process), the kernel moves the process from the not-ready list 
the end of the “ready” list, and returns a description of the event to the proces 


Note that each “event generator” (i.e., mouse, keyboard, and timer) has its 
buffer, which ensures that no event is “dropped on the floor”, or lost, whil 
another is being processed, 


‘The screen manager tracks the mouse pointer on the screen, and manages 
dows and menus. It signals when a mouse bution is pressed with the mov 
pointer fixed on a significant area of the screen (e.g, the work area in a Wi 
Gow), returns a message when the user manipulates a window, and drops ft 
appropriate menu when the pointer crosses into the menu bar at the top of the 
sereen, 
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AES 


Finally, AES contains a number of sets, or “libraries”, of functions that create 
and manipulate screen elements, These functions are accessed through the 
library libaes.a, and their bindings are carried in the file aesbind.h, 


‘The following names each AES routine and briefly describes what it does. 


appl_exit 
appl_find 
appl_i 
appl_read 
appl_tplay 

appl_trecord 
appl_write 


evnt_button 
evnt_delick 
evnt_keybd 
eynt_mesag 
eynt_mouse 
evnt_multi 

evnt_timer 


form_alert 
form_center 
form_dial 
form_do 
form_error 


fsel_input 


graf_growbox 
graf_handle 
graf_mbox 
graf_mkstate 
graf_mouse 
graf_rubbox 
graf shrinkbox 
graf slidebox 
graf_watchbox 


menu_bar 
menu_icheck 
menu_ienable 
menu_register 
menu_text 

menu tormal 


obje_add 
obje_ change 
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tell the AES that the program is exiting 
get another application’s handle 
initialize a new application 

read a message from another process 
replay recorded AES events 

record AES events 

send a message to another process 


await a mouse button event 
set/get double-clicking speed 
await a keyboard event 

awaita message 

wait for mouse to enter a rectangle 
await more than one event 

wait a given amount of time 


perform an alert dialogue 
center dialogue box on screen 
reserve/release dialogue box 
use dialogue box 

display preset error box 


display/run file selector box 


draw expanding box outline 
return VDI handle 

draw moving box 

return current mouse states 

change mouse pointer's shape 

draw box that expands with mouse pointer 
draw a shrinking outline 

find center of box's “slider” 

check if mouse pointer is within box 


display/erase menu bar 

display/remove checks by menu items 
enable/disable menu items 

name desk accessory on desk menu 
change text of menu item 

show menu tile in normal/reverse video 


add an object to object tree 
change an object’ state 
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obje delete delete object from object tree 
obje_draw draw an object 
obje_edit edit text within an object 
obje_find find if mouse is over an object 
obje_order change order of object within its tree 
obje_set compute object’s location 
re_copy copy a rectangle 
re_equal compare two rectangles 
re_interseet _calculate overlap of rectangles 
re_union combine rectangles 
rsre_free free memory allocated to resource 
rsre_gaddr get address of data structure 
rsre_load Toad resource file into RAM 
rsre_obfix convert character coordinates 
rsre_saddr store index to data structure 
serp_read find name of scrap directory 
serp_write set name of scrap directory 
shel_envrn search for environmental variable 
shel_find find a file name 
shel_read return name of parent program 
shel_write invoke another program or exit from GEM 
wind_cale calculate window size 
wind close _close a window 
wind_ereate create a window 

ind delete delete window 
wind_find find a window under mouse pointer 
wind get get information about a window 
wind_open open a window 
wind_set set values for window 


wind_update —_inhibit/allow updates to windows 


Each routine has its own entry within the Lexicon; its bindings are given, with 
2 fuller description and, often, an example. 


Programming the AES 
Some graphics-based systems have been designed to automate as much work as 
possible. The AES is not such a system. In programming the AES, you must 
specifically guide cach function each step of the way. This means that you 
must do more work, but it also means that you have fuller, and finer, control of 
the operation of the program. For example, program flow under an’ automated 
system often appears to Function as follows: 
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AES. 


i (action was desired) 
Pa 


else 
‘sough_luek; 


Programming under the AES more often resembles the following model: 
information received /* e.g., mouse moved, Keyboard pressed */ 
parse information 


SF Cinformation maste teet) ¢ 
pass, to_rautineCinformation); 


cleanup. debris(); 

9 alse if (information meets second test) ¢ 
‘pass_to_atherrout inet information); 
‘take_al ternative setion(): 
cleanup. debrist); 

2 else ignore(); 


The second model of programming obyiously is harder to work with than the 
first. However, it has the advantage of protecting you from random, system 
generated errors—or at least gives you the tools with which to work around such 
errors should they occur, 


In programming for AES, note that each process must be declared to the AES 
through the function appl_init. This gives the process a handle, so it can be 
recognized and manipulated by the kernel, and notifies the AES that this 
program is a GEM application. When a process is finished, it is good practice 
to close it with the function appl_exit. This frees up AES structures allocated to 
the process, and ensures that the Process terminates gracefully. 


Note that not all © programs use the AES specifically. Programs that use only 
UNIX routines or STDIO need never worry about the AES. All programs that 
use the graphics interface, however, must run under the AES; this means that 
all programs that use the VDI must begin with appl_init and close with ap- 
pl_exlt, 


The AES provides sophisticated routines to help draw windows and menus, and 
create graphics objects. See the entries for window, menu, and object for more 
details, 


For information about compiling AES programs, see the entry for TOS, 


See Also 


aesbind.h, gemdefs.h, libaes.a, libvdi.a, menu, object, TOS, window 
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aesbind.h—Header file 


alignment—Definition 


Notes 
‘The AES binding library uses the object file erystal.o to access the AES ser- 
Vices, A program should never call this function directly; it is automatically 
linked with libaes.a. You should never name a function or a global variable 
crystal if your program uses the AES. 


Note that both the AES and the VDI use trap 2 to access the services. 


aesbind.h is the header file that declares the the GEM AES routines contained 
in the library libaes.a, and shows a sample call for each. It also defines the 
following structures: 


Rect Describe a rectangle by its x, y coordinates and its width and height. 
This structure is called GRECT in the header file obdefs.h, and is 
described as follows: 


‘typedef struct € int x, ¥, w, hy) Rect; 


Mouse Pass pointers to the x, y coordinates, mouse button state, and keyboard 
state: 


typtdet struct C int *y, *y, *B, tk; > Houses 
Prect Pass pointers to the x, y coordinates, width, and height of a rectangle: 
typedef struct € int *, ty, ‘hy Yh: 2 Prects 


See Also 
AES, header file, TOS 


Alignment refers to the fact that the address of a dats entity must be aligned on 
a certain numeric boundary in memory, such that address modulo mmber e- 
quals zero. For example, on 68000 and the PDP-11, an integer must be aligned 
along an even address, ive,, address%2==0. Generally speaking, alignment is a 
problem only if you write programs in assombly language; for C programs, 
Mark Williams C will ensure that data types are aligned properly under most 
foreseeable conditions. 


Alignment may be a problem when porting programs to the VAX. On this 
computer, certain data types have quad-word boundaries, and exceeding these 
boundaries can mean a significant penalty in the speed with which programs 
execute. 


Processors react differently to alignment problems; an alignment problem on the | 
VAX or the 8085 causes programs to run more slowly, whereas on the 68000 
they cause bus errors, 


appl_exit-appl_init 


See Also 
ata types, declarations 


appl_exit—AES function (libaes.a/appl_exit) 
Exit from an application 
#include <aesbind.h> 
int appl_exit() 
appl_exit is an AES routine that notified the AES that the program no longer 
requifes its services, It frees up the AES structures and the handle associated 
with the process. Tt does not terminate program execution. 
appl_exit returns zero if an error occurred, and a number greater than zero if 
one did not. 
Example 
For examples of how to use this routine, see the entries for evnt_multi 
window. 
See Also 
AES, appl_i 


nd 


it, TOS 


appl_find—AES function (libaes.a/appl_! 
Get the ID of another application 

clude <aesbind.h> 

int appl_find( filename) char *filename; 

appl_find is an AES routine that fetches the handle of another application. 

filename is the name of the file in which the application is stored; it cannot be 

innger than eight characters appl_find returns the handle if it is found, and -1 

if an error occurred, 

See Also 

AES, TOS 


AES function (ibae: 
Initiate an appli 
#include <aesbind.h> 
int appl_init() 

appl_init is an AES routine that declares an application. It registers the ap- 
plication with AES, and initializes all resources used by the the application. Tt 
returns the application’s handle if all went well, and -1 if an error occurred, 


appli 
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appl_read—AES function (libaes-a/appl_tead) 


appl_tplay—AES function (libaes.a/appl_tplay) 


appl_trecord—AES function (libaes.a/appl_trecord) 
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Example 
For an example of this routine, sec the entries for evat_multi, menu, object 
and window. 


See Also 
AES, appl_exit, TOS 


Read a message from another application 
#include <aesbiad.h> 


int appl_read(handle, length, buffer) int handle, lengit; char *buffer; 


appl_read is an AES routine that reads a message from another application. 
handTe is the AES handle of the application that owns the pipe to be read, and 
Tength is the number of bytes to read from the pipe, buffer is the place into 
which the message is written, Tt returns zero if an error occurred, and a num= 
ber greater than zero if one did not. 


Note that this routine is used only in specialized programming situations, to 
receive messages sent with the routine appl_write. Normally, an application 
receives messages by using the routines or eymt_multi. 


See Also 
AES, appl_y 


te, evnt_mesag, TOS 


Replay AES activity 

#include <aesbind,h> 

Int appl_tplay(&u/fer, number, speed) char *buffer; Int number, speed; 
appl_tplay is an AES routine that replays a set of AES events. These events: 
must be recorded with the function appl_trecord. buffer is the name of the: 
buffer in which the actions are stored, number is the number of actions that 
you wish to replay, and speed is a number from one to 10,000 that indicates 
how fast the actions should be replayed. appl_tplay always returns one 

See Also 

‘AES, appl_trecord, TOS 


‘Record user actions 

#include <aesbind.h> 

int appl_trecord(buffer, capacity) char *huf fer; int capacity; 

appl_trecord is an AES routine that records a user's AES actions. Each 
recorded action requires an int and a long’s worth of storage. The int indicates 
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appl_write-ar 


the type of event being recorded, as follows: 
0 timer event 
1 mouse bution event 
2 mouse event 
3 keyboard event 


The long can hold a variety of information, depending on the type of event 
being recorded, as follows: 


timer milliseconds elapsed 

button —_low word: state (0=up, 1=down) 
high word: number of clicks 

mouse low word: X coordinate 


high word: ¥ coordinate 

keyboard low word: character typed 

high word: keyboard state 

buffer is the buffer into which the user's actions are recorded. capacity is the 
number of events that can be stored, This should equal the amount of ‘storage 
available to buffer, divided by six (the number of bytes used by each event). 
appl_trecord returns the number of events actually recorded. These events can 
be réplayed with the function appl_tplay. 
See Also 
AES, appl_tplay, TOS 


appl_write—AES function (libaes.a/appl_write) 
‘Send a message to another application 
include <aesbind,h> 


int appl_write(handle, length, buffer) int handle, length; char *buffer: 


appl_write is an AES routine that sends a message to another application. 
handle is the handle of the application to which the message is being sent, and 
length is the length of the message, in bytes. buffer gives the address where 
ow write your message, appl_write returns zero if an error occurred, and & 
‘umber greater than zero if oné did not. 


Note that this routine is used only in specialized programming situations, The 
target application must use the routine appl_read to receive messages sent via 
appl_write. 

See Also 

AES, appl_read, TOS 
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ar—Command 
‘The librarian/archiver 
at option [modi fierllposition| archive [member 


‘The librarian ar edits and examines libraries. It combines several files into. a 
file called an archive or library. Archives reduce the size of directories and 
allow many files to be handled as a single unit, The principal use of archives ig 
for libraries of object files. The linker Id understands the archive format, and 
can search libraries of object files to resolve undefined references in a program. 


The mandatory aption argument consists of one of the following command keys: 


d Delete each given member from archive. The ranlib header is updated if 
present. 


m — Move each given member within archive. If no modifier is given, move. 
each member to the end, The ranlib header is modified if present. 


Print each member, This is useful only wi 


archives of text files. 


Quick append: append each member to the end of archive unconditionally, 
‘The ranlib header is nor updated. 


rt Replace each member of archive. The optional modifier specifies how to 
perform the replacement, as described below. The ranlib header is 
modified if present. 


t Print a table of contents that lists each member specified. If none is 
given, list all in archive. The modifier y tells ar to give you additional in= 
formation. 

x Extract each given member and place it into the current directory, If 


none is specified, extract all members. archive is not changed. 


The modifier may be one of the following, The modifiers a, b, i, and u may be 
used only with the mand r options, 


If member does not exist in archive, insert it after the member named by. 
the given position, 


b If member does not exist in archive, 
the given position. 


insert it before the member named by | 


¢ Suppress the message normally printed when ar creates an archive. 


i If member does not exist in archive, insert it before the member named by 
the given position. This is the same as the b modifier, described above. 

k Preserve the modify time of a file, This modifier is useful only with the 
1, q, and x options. 


s Modify an archive’s ranlib header, or create it if it does not exis 
used only with the r, m, and d options. 


This is 
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u Update archive only if member is newer than the version in the archive. 
y Generate verbose messages. 


All archives are written into a specialized file format. Each archive starts with 
2 “magic number” called ARMAG, which identifies the file as an archive, The 
members of the archive follow the magic number; each is preceded by an 
ar_hdr structure, as follows: 


adefine DIRSIZ 14 


‘édetine ARKAG 0177535 1 wagic umber */ 

peruct ar_her © 
char ar_nope tDIRSI2); 1 ener name */ 
inet ar dat 7 tine inserted */ 
shore ar gids 7 group ouner */ 
short aru 7 user aver */ 
short ar_node; ff File mode 47 
size_t ar_size; /* file size */ 


» 


‘The structure at the head of each member is followed the data of the file, 
which occupy the number of bytes specified by the variable ar_size. 


See Also 
commands, 1d, am, ranlib 


Notes 

It is recommended that each object-file library you create with ar have a name 
that begins with the string lib. This will allow you to call that library with the 
=I option to the ee command. 


Note that ar now adjusts the time file in the ranlib header $0 that out-of-date 
ranlib headers are now dated in 1970, and up-to-date ranlib headers are deted 2 
decade into the future. This should eliminate improper outdated ranlib error 
messages from the linker. 


arena—Definition 

Mark Williams C uses an arena, rather than a heap, for allocation of dynamic 
memory, An arena is the area of memory that is available for @ program to 
allocate dynamically at run time. It consists of an area of memory that is 
divided into allocated and unallocated blocks. The unallocated blocks together 
form the “free memory pool” 


Portions of the arena can be allocated using the functions malloc, calloc, or 
realloc; returned to the free memory pool with free; or checked to see if they 
are allocated or not with notmem, 
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See Also 
calloc, free, malloc, notmem, realloc 


arge—Definition 
Argument passed to main 
int arge; 


arge is an abbreviation for argument count. It is the traditional name for the 
first argument toa C program's main routine, By convention, it holds the num- 
ber of arguments that are passed to main in the argument vector argv. Note that 
because argvi0] is always the name of the command, the value of argc is always 
one greater than the number of command-line arguments that the user enters, 


Example 

For an example of how to use arge, see the entry for argy. 
See Also 

argy, main 

The C Programming Language, page 110 


argy—Definition 
‘Argument passed to main 
char *argull 


argy is an abbreviation for argument vector. It is the traditional name for a 
pointer to an array of string pointers passed to a C program's main function, 
and Is by convention the second argument passed to main. Note that by conven= 
tion, argy[0] always points to the name of the command itself. 


Under the draft ANSI standard for the C language; the default arguments toa 
CC program are int arge and char targyll. Mark Williams C passes these ar~ 
gumens and looks for them in two different ways: in the command tail of the 
basepage sructure, and in the environment. 


Why @ different convention? 

‘TOS allows programs to be run ina number of different ways: under a shell, 
from the desktop with arguments (.ttp), or from the desktop without arguments 
(.tos, .prg). The Mark Williams conventions for passing argument are designed 
to increase run-time flexibility; programs compiled under Mark Williams C 
should run transparently from the shell, or from the desktop, using every pos~ 
sible run-time environment, 


Using the environment to pass parameters also has the advantage of lifting the 
limit on the number or size of arguments that can be passed; it also has the ad~ 
vantage of not mapping all of the arguments to upper case. 
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TOS conventions i 
The current TOS convention for passing arguments is to pass up to 127 charac 
ters in the command tail of the Pexee command. If the tail is parsed by the 
Gesktop, it will be limited to 40 upper-case characters. 


Mark Williams convention 
The Mark Williams convention is first to parse the argument into words, then 
pass the words within the Pexee environment, Within the Pexec environment, 
the arguments begin immediately after the environmental variable ARGV and 
continue to the end of the environment, The arguments may contain any ASCIT 
Character except NUL, which is used to terminate both individual arguments 
and the Pexec environment as a whole. 


‘The Mark Williams library function execve executes a given command with a 
specifed argy and envp. Tt copies envp into an allocated buffer, appends the 
string ARGV=iovector environment, and then appends the strings to the array to 
which argy points, This concatentation of strings, which is terminated by an 
empty string, becomes the environment passed to Pexec. In another part of the 
allocated buffer, exeeve concatenates up to 127 characters, starting with 
argvf i] and continuing through argv/ ], separating the arguments with spaces. 
This concatenation of strings, which is prefixed by a count, becomes the com- 
mand tail passed to Pexec. When exeeve now calls Pexec(0, command, com- 
‘mand_tail, environment), TOS copies environment into a newly allocated buffer, 
copies command rail into the newly allocated basepage, loads command, and ex- 
ecutes it, 


Summary 

Mark Williams C puts the arguments into the environment so that programs that 
use the the Mark Williams run-time start-up routine, efts0.0, will find them 
there, It puts them into the command tail, so that programs that use the 
«ttp-style run-time start-up (ertsg.o) will find them there. 


The Mark Williams run-time start-up module, crts0.o, looks for arguments in 
the environment. If it finds them there, it uses them. If no arguments were 
Found in the environment, crts0.0 assumes that it was started from the desktop 
or 2 TOS convention command line interpreter, so it looks in the command tail 
and parses the contents info arguments that are delimited by space and tab 
characters, 


Mark Williams C looks for arguments in the environment because a command 
may need more arguments than can be fit into the 40-character command tail 
available when program is run with the .ttp feature. In addition, a command 
(e.g., egrep) can take arguments that contain literal spaces or tabs; these would 
be interpreted to be word separators if arguments were passed simply through 
the command tail, 


As a last resort, Mark Williams C also looks for arguments in the command tail, 
because 40 characters mapped to upper case are better than nothing. 
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The execve function passes arguments in both the environment and the com= 
mand tail, and the run-time start-up routine erts0.o takes arguments from the 
command tail if the environment has none, Mark Williams C uses both conven 
tions in both places to allow as meny programs to work in as many environ= 
ments as possible. 


Example 

This example demonstrates both arge and args[], to create the command echo, 
For another example of arge, see the entry for basepage. 

naincarge, argv) 

int argez char *erevtl; 

© 


for i 


i < argc; » ¢ 
printfitist, argvtild: 
Tf (ori < arge) 

puteharc? 195 
> 


putchar(at 
return 0; 


y 


See Also 
arge, crts0.0, ertsd.o, ertsg.o, main, Pexee 
The C Programming Language, page 110 


array—Definition 


66 


An array is a collection of data elements of the same type or structure, which 
are stored in consecutive memory and which share the same name but are dif- 
ferentiated by a subscript. For example, the array fool3] has three elements: 
fool0}, fool], and foof2]. 


Note that the numbering of elements within an array always begins with *( 


Arrays, like other data elements, may be automatic (auto), static, or external 
(extern). 


Arrays can be multi-dimensional; that is to say, each element in an array can it- 
self be an array. To declare a multi-dimensional array, use more than one set 
of square brackets. For example, the multi-dimensional array foof3]10] is 2 
two-dimensional array that has three elements, each of which is-an array of ten 
elements, Note that the second sub-script is always necessary in a multi- 
dimensional array, whereas the first is not, For example, fool][10] is acceptable, 
whereas fool 10Il] is not: the first form is an indefinite number of ten-element 
arrays, which is correct C, wheres the second form is ten copies of an in- 
definite number of elements, which is illegal. 
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The C Programming Language, page &3, forbids the initialization of automatic 
arrays. Mark Williams C lifts this restriction, It allows you to initialize 
automatic arrays and structures, provided that you know the size of the array, 
or of any array contained within a structure, The initialization has the same 
form as that of the external aggregate, but is performed on entry to the routine 
instead of at compile time. Note, however, that because this feature is not 
defined as part of the language,’ its use will limit the portability of your 
program. 

See Also 

declarations, flexible array, struct 

The € Programming Language, pages 25, 83, 210 


as—Command 


“Mark Williams assembler 
as [-glx] [-0 outfile] file .. 


as is the Mark Williams assembler. It consists of one program, called as, which 
turns files of assembly language into relocatable abject modules, similar to those 
produced by the C compiler, Relocatable object modules produced by the as- 
sembler and the compiler are of the same format. 


as is a multipass assembler for writing small subroutines in assembly Tanguage. 
Because it is not intended to be used for full-scale assembly-language program- 
ming, it lacks many of the more elaborate facilities of full-fledged assemblers, 
such as conditional compilation or user-defined macros. However, as dots op- 
Limize span-dependent instructions. 


w 


Normally, the assembler as is invoked automatically by ce to assemble programs 
with a suffix of .s, However, you can invoke as directly from the shell msh, by 
using the following command: 


as [-glxl|-0 outfile] file 
‘The following describes the available options: 


~0 Write the assembled executable into outfile. The default is lout. 


-2 Give all symbols that aré undefined at the end of the first pass the type 
undefined external, as though they had been declared with 2 .globl direc~ 
tive. 


-1 Generate a listing on the standard output. 


-x Strip all non-global symbols that begin with the character ‘L’ from the 
symbol table of the object module, This speeds the linking of files by 
removing compiler-generated labels from the symbol table. 
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Lexical conventions 
Assembler tokens consist of identifiers (also known as “symbols” or 
constants, and operators. 


An identifier is a string of alphanumeric characters, including the peried ‘? and | 
the underscore *_'. The first character must not be numeric. Only the first 16 
characters of the name are significant; the rest are thrown away, Upper case 
and lower case are different. The machine instructions, assembly directives, 
and symbols that are used frequently are in lower case, 


“names! 


Numeric constants are defined by the assembler by using the same syntax as the. 
C compiler: a sequence of digits that begins with a zero ‘0" is an octal constant; a 
sequence of digits with a leading ‘Ox’ is a hexadecimal constant (‘A’ through ‘F 
have the decimal values 10 through 15); and any strings of digits that do not 
begin with ‘0" are interpreted as decimal constants. 


‘A character constant consists of an apostrophe followed by an ASCIT character. 
The constant’s value is the ASCII code for the character, right-justified in the 
machine word. 


A blank space can be represented either as 0x20 (its ASCH value in 
hexadecimal), or as an apostrophe followed by a space ('), which on paper 
looks like just an apostrophe alone. 


‘The following gives the multi-character escape sequences that can be used in a 
character constant to represent special characters: 


\b Backspace (0010) 
\f — Formfeed (0014) 
\a Newline (0012) 
\r Carriage return (0015) 
\t Tab (oot) 
\v Vertical tab (0013) 
\imt Octal value (Onnn) 


Spaces and tab characters can be used freely between tokens, but not within 
identifiers. A space or a tab character must separate adjacent tokens not other 
wise separated, eg, an instruction opcode and its first operand. 

Masks 

‘as accepts a register mask syntax for the movem instruction. The syntax is as 
follows: 


oven ‘Seemask, “(<a> 
‘mover ‘Sefnaste,<ade> 
even eor> Sefmask> 
mmoven (ans }e, Sefnaske 


‘The abbreviations between angle brackets ‘<’ '>! mean the following: 
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The registers a0 through a7. 


‘The effective address (not register direct), ie., the location of the 
address. 


<rmask> (reverse mask) This can be either a word whose bits show which 

registers to save, with bit 0 indicating register a7 to bit 15 in 

dicating register d0; or a list of the registers to save, enclosed in 

braces *(’*)’ 

<fmask> (forward mask) This, too, is either a word whose bits show which 
registers to save or restore, with bit 0 indicating register dO through 
bit 15 indicating register a7; or a list of these registers enclosed in 
braces, 


Note that if the {lis} variety of mask is used, the assembler automatically 
produces a consistent value for all addressing modes (bits backward for destina~ 
tion, minus the contents of register aN). If a word value is used, the bits are 
not modified. Thus: 


oven. -$€62+47,2-25D, (50) 
wmoven.{ —_(sp)+,$¢02-d7, 82-05) 


produces the same code as: 


mover. SOXSF5C,-(sp) 
oven. (spi ,S033CFC 

‘Note, too, that ranges that include both register sets are allowed; thus 
oven. S495), 4¢05) 


will save dO through 25. The instruction 


oven. $C05-a0),4¢05) 
does the same thing. Likewise, 

oven. $Ce2, 5-5, 83,5872, (sp) 
results in code that saves d2, d3 through d5, a3, and aS through a7. The in- 
struction 

maven. $€302,-¢5p) 
saves dO. 
Commenis 


Comments are introduced by a slash ('/") and continue to the end of the line, 
The assembler ignores all comments. 


Program sections 

‘The assembler permits the division of programs into a number of sections, each 
corresponding (roughly) to a functional area of the address space. Each 
Program section has its own location counter during assembly. The eight 
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program sections are subdivided into three groups that contain code and data, as 
follows: 


shared: shri shared instruction 
shrd shared data 
private: prvi private instruction 
prvd private data 
uninitialized: bssi_—_ uninitialized instruction 
bssd uninitialized data 
strn strings 


All Mark Williams assemblers use the same set of sections; this increases the 
portability of programs among operating systems, In most instances, the 
programmer need not worry about what all of the program sections are, and can 
simply write code under the keywords .prvi or .shri, and write data under the 
keywords .prvd or .shrd. At the end of assembly, the sections of a program are 
concatenated so that within the assembly listing the program fooks like a con- 
tiguous block of code and data. 


The current location 
The special symbol *.’ (period) is a counter that represents the current location. 
The current location can be changed by an assignment; for example: 


.= 4START 


‘The assignment must not cause the value to decrease and it must not change the 
program section, i.e,, the right-hand operand must te defined in the same sec- 
tion as is the current section, 


Expressions 

‘An expression is a sequence of symbols that represent a value and a program 
section. Expressions are made up of identifiers, constants, operators, and 
brackets. All binary operators have equal precedence and are executed in a 
strict left-to-right order, unless altered by brackets. Note that square brackets, 
‘{ and ‘J, are used to group the elements of expression, because parentheses are 
used for addressing indexed registers. 


Types 
Every expression has a type, which is determined by that expression’s operands. 
The simplest operands are symbols, which yield the following types: 


undefined A symbol is defined if it is a constant or a label, or when it is 
assigned a defined value; otherwise, it is undefined, A sym- 
bol may become undefined if it is assigned the value of an 
undefined expression. It is an error to assemble an undefined 
expression in pass 2, With option fB-gfR, pass 1 allows as 
sembly of undefined expressions, but phase errors may be 
produced if undefined expressions are used in certain con- 
fexts, such as ina .blkw or .blkb. 
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absolute An absolute symbol is one defined ultimately from a constant 
or from the difference of two relocetable values of the same 
type. 

register ‘The machine registers. 

Relocatable All other user symbols are either defined labels (in a program 


section) or externals, These are relocated at link time. Every 
user program section and external symbol defines a unique 
type class, 

Each keyword in the assembler has a secret type that identifies it internally; 

however, all secret types are converted to an absolute constant in expressions, 

‘Thus, any keyword can be used in an expression to obtain the basic value of the 

keyword. 


‘Note that the type of an expression does not include such attributes as length, so 
the assembler will not remember whether a particular variable was defined as a 
word or a byte. Addresses and constants have different types, but the assembler 
does not treat a constant at an immediate value unless it is preceded by a doliar 
sign ‘S’. If a constant is used where an address is expected, the constant will be 
treated like an address (and vice versa). The programmer must distinguish be 
tween variables and addresses or immediate values, 


Operators 
‘The following table shows various characters interpreted as operators in expres- 
sions. 


+ Addition 
- Subtraction 
Multiplication 

- — Unary negation 

~  Unary complement 

* Type transfer (cast) 

| Segment construction 
Type propagation 
When operands are combined within expressions, the resulting type is a func- 
ton of both the operator and the types of the operands. The ‘**,*~", and unary 
‘= operators can manipulate only absolute operands and always yield an ab- 
solute result, 


The '+' operator signifies the addition of two absolute operands to yield an ab- 
solute result, and the addition of an absolute to a relocatable operand to yield a 
result with the same type as the relocatable operand. 

The binary ‘* operator allows two operands of the same type, including 
relocatable, to be subtracted to yield an absolute result; it also allows an ab- 
solute to be subtracted from a relocatable, to yield a result with the same type 


n 


as 


Lexicon 


as the relocatable operand, 


‘The binary ‘*' operator yields a result with the value of its left operand and the 
type of its right operand. It may be used to create expressions (usually intended 
to be used in an assignment statement) with any desired type. 

Statements 

‘A program consists of a sequence of statements separated by newlines or by 
semicolons, There are four kinds of statements: null statements, assignment 
statements, keyword statements, and machine instructions, 


‘Any statement may be preceded by any number of labels, There are two kinds 
of labels: name and temporary. 


‘A name label consists of an identifier followed by a colon (‘). The program 
section and value of the label are set to that of the current location counter. It 
is an error for the value of a label to change during an assembly. This most of- 
ten happens when an undefined symbol is used to control a location counter ad- 
justment. 


A temporary label consists of a digit (‘0" through ‘9') followed by a colon 
Such a label defines temporary symbols of the form xf and xb, where x is the 
digit of the label, References of the form xf refer (a the first temporary label 
x: forward from the reference; those of the form xb refer to the first temporary 
label x: back from the reference. Such labels conserve symbol table space in the 
assembler. 


A null statement is an empty fine, or a line that contain only labels or a 
comment. Null statements can occur anywhere, They are ignored by the as— 
sembler, except that any labels are given the current value of the location 
counter. 


Note that the programmar is responsible far proper alignment of data. See the 
entry on alignment for more information. 


Assignment statements 

‘An assignment statement consists of an identifier that is followed by an equal 
sign ‘=" and an expression. The value and type of the identifier are set to those 
of the expression. Any symbol that is defined by an assignment statement may 
be redefined, either by another assignment statement or bya label. An assigi 
ment statement is equivalent to the equ keyword statement found in many as~ 
semblers. 


Assembler directives 
‘Assembler directives give instructions to the assembler. Each directive keyword 
begins with a period, and some are followed by operands, 


Changing the current program section 
These directives change the current program section to the named section, 
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cbssd. sshrd 


chssi «shri 
wpevd vstrn 
cprvi 


The current location counter is set to the highest previous value of the location 
couater for the selected section, 


string 
Tn this directive, the first non-whitespace character, typically a quota— 
tion mark, after the Keyword is taken as a delimiter. Successive 
characters from the string are assembled into successive bytes until this 
delimiter is again encountered. To include a quotation in a string, use 
some other character for the delimiter. 


Tt is an error for a newline to be encountered before reaching the final 
delimiter, The multi-character escape sequences that are described 
above in the subsection Constants may be used in the string to 
represent newlines and other special characters. 


-bikb expression 
This directive assembles blocks that are filled with zeros. The size of 
the block is expression bytes. 


sbikl expression 
This directive assembles blocks that are filled with zeros. The size of 
the block is expression longs. 


sblkw expression 
This directive assembles blocks that are filled with zeros. The size of 
the block is expression words. 


byte expression | , expression | 
Here, thé expressions in the list are truncated to byte size and as 
sembled inta successive bytes. Expressions in the list are separated by 
commas. 


seven The directives .evem and .odd force alignment by inserting NUL, if 
necessary, 10 set the location counter to the next even or odd location, 
respectively. 


splobl identifier {, identifier | 
Here, the identifiers separated by commas are marked as global. If 
they are defined in the current assembly, they may be referenced by 
other object modules; if they are undefined, they must be resolved by 
the linker before execution. 


long expression |, expression} 
In this directive, the expressions in the list ate truncated to long and 
the resulting data are assembled into successive longs. Expressions in 
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the list are separated by commas. 
jage This causes the assembly listing to skip to the top of a new page by in— 
serting a form-feed character into the file. The title is printed at the 
top of the page. 
stitle string 
Here, string appears on the top of every page in the assembly listing. 
This directive also causes the listing to skip to a new page. 
odd The directives .even and .odd force alignment by inserting NUL, if 
necessary, to set the location counter to the next even or odd location, 
respectively. 
sglobl identifier [, identifier ] 


sword expression | , expression | 
“The expressions in this list are truncated to word size and the resulting 
data are assembled into successive words. Expressions in the list are 
separated by commas, 
Conventions 
€ compiler conventions, naming conventions, function calling conventions, the 
management of arguments, and return values are all described in detail in the 
Lexicon entry for calling conventions. 


68000 register names 

The assembler for the Motorola 68000 microprocessor uses a subset of the 
machine opcodes and register names provided by the manufacturer's assembler. 
All unsupported names are longer synonyms for names that are supported. 
‘Assembler directives, statement syntax, and expression syntax are different. 


‘The following register names are predefined, In general, length of operation is 
Specified by opcode, The -I suffixes are used uuily in indesed addiessing to 
differentiate 16-bit and 32-bit indices, 


16-bit 32-bit 


usp sp 
cer pe 

st cin 
do dit 
dl at 
a2 Bl 
a3 dad 
ad 45.1 
45 46.1 
a6 7d 
a7 a0 
a0 all 
al al 
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a2 Bl 
33 ad.t 
ad 35.1 
a3 26.1 
a6 ald 
al spl 


Address descriptors 

The following syntax is used for general source and destination address descrip- 
tors. The syntax is a subset of that used by Motorola assemblers, except that the 
character ‘$' is used to specify immediate data, and that the suffix :s appended 
to an absolute address forces absolute short addressing. Note that short address 
modes are nor supported by the TOS system executable format. 


In the examples, the symbols a, d, and r refer to address, data, and any register, 
respectively, and the symbol ‘e’ refers to any expression. 


dn Data register direct 

Address register direct 
(@) Address register indirect 
(a)+ Address register postincrement 
=(a) Address register predecrement 
e(a) Address register displacement 


e(ayr) Address register short index 
e(ayril) Address register long index 


es Absolute short address 
e Absolute long address 
e(pe) Program counter displacement 


e(pe,r) Program counter short index 

e(pevr.l) Program counter long index 
Immediate data 

i Label 


ea represents the effective address of any data address. am indicates any 
register from a0 to a7; dn, any register from dO to d7. 

The addressing modes are classified into four categories that are used in the in 
struction listings to distinguish allowed addresses: 


Data addresses are all addresses except address registers. 


* Memory addresses are all addresses except data and address regis 


ers. 
* Control addresses are all memory addresses, except address register 
predecrement and address register postinerement. 

Alterable addresses are all addresses except program counter displacement, 
program counter index, and immediate. 


Failure to observe category restrictions will generate address errors, 
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Machine instructions 
The following machine instructions are defined, For the most part, they form g 
subset of the instructions provided by Motorola assemblers that eliminates I 
synonyms such as bsr.l or add.w. The conditions hs (higher or same) and 
(lower) are provided as synonyms for ce (carry clear) and cs (carry set), 


In the examples an, dn, and rm refer to address, data, and registers, ea refers t 
general effective addresses, I refers to direct addresses, e refers to a general ex 
pression, and n refers to an absolute expression, 


Many syntactically correct instructions may prove ta have semantic errors b 
cause of restrictions of effective addresses to data, alterable, memory, or conti 
categories. Contrary to appearances, no 68000 instruction operates oa all 

dressing modes; some modes are always forbidden, These restrictions are not 
at the end of each instruction description in the 68000 user’s manual. In ti 


following listing, instructions have been classified according to their allow. 
addressing modes. Each classification is named by the lexicographically first 
instruction in the class, 


ABCD Type: These instructions accept only two kinds of operands: data register 
direct and address register predecrement, The BCD instructions operate on byte 
size operands only. j 


abed 
abed 


abed 
addx 
addx.b 
addx1 
sbod 
subx 
subx.b 
subx.t 


ADD Type: These instructions take a data-register source to a memory-alterable 
destination or any source to a data-register destination. If the operation size is 
byte, then address-register direct sources are forbidden. 


add dn.ea 
add ea,da 
add D040 
add.b O00 
add.l D080 
sub ‘9040 
subb 9000 
sub, 9080 


ADDA Type: These instructions accept any source effective address. The cmp 
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instruction cannot combine byte operations with address-register sources, 


adda eaan Deco 
addal aan DIco 
cmp ea,da BOO 
emp.b —ea,da B000 
empl ea,da B080 
compa = eaan BOCO 
cmpal — ea,an BICO 
movea  ea.an 3040 
moveal eavan 2040 
suba eaan 900 
subal exam 91c0 


ADDI Type: These instructions require a data-alterable destination-effective 
address. The nbed instruction, set according to condition, and the tas instruc~ 
tions are implicitly byte sized. 


addi Sn,ea 0640 
addi Sea 0600 
addil — $n.ea 0680 
ea 4240 
ea 4200 
ea 4280 
Sn,ca oc4o 
$n.ca ‘coo 
Snjea cao 
dnjea B140 
nea B100 
dnjea BI80 
ea 4800 
ea 4480 
ea 4400 
ea 4480 
ea 4040 
ea 4000 
ea 4080 
ea 4640 
ea 4600 
ea 4680 
ea 54C0 
ea 55C0 
ea 5760 
ea 51C0 
ea 5cC0 
ca SECO 
ea 52C0 
ea 54C0 
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sle ea SECO 
slo ea 55C) 
sis ea 33c0 
sit ea SDCO 
smi ea 5BC0 
sne ea 5600. 
spl ea SACO 
st ea 50c0 
subi Snyea 0440 

subib  Snyea 0400 

subil — Snjea 0480 

sve ea 58C0 
svs ea 590 
2s ca 4Aco 
tst ea 440 
Istb ea 400 
tstl ea 480 


ADDQ Type: These instructions take an immediate-source operand in the ran} 
1 to 8 and an alterable effective-address destination operand. If the operation 
size is byte, then address-register direct destinations are forbidden. 


addq Sea 5040 
addg.b — Snea 5000 
addal — Sn,ea 5080 
subg Sea 5140 
subg.b — Sn,ea 5100 
suba.l  Sn,ea 5180 


AND Type: These instructions take two forms: data register direct source to 
memory-alterable destinations, and data source effective address to a data 
register direct destination. 


and dn,ea 
and ea.dn 
and co4o 
andb C000 
andl C080 
or 8040 
orb 8000 
orl 8080 


ANDI Type: These instructions combine an immediate source operand with 
either a data-alterable effective address destination operand or the status 
register. The whole status register or only the low byte is selected, depending 
on whether the operation size is word or byte. 
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andi 
andi 
andi 
andib 
andi 
eori 
eori.b 
eori.l 
ori.b 
ori 


Sn.ea 
Snsr 


0240 
0200 
0280 
0Ad0 
0400 
OAg0 
040 
0000 
0080 


‘ype: The shift instructions come in three flavors: immediate shift count 


of data register, data register shift count of data register, and shift by one of a 
word at_a memory-alterable effective address. The memory shift opcode is 
formed from the opcodes given by setting bits 6-7, and by moving bits 3-4 to 


positions 9-10. 


ash 
asl 
asl 


asl 
asl.b 
asl 
ast 
ash 
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$n,dn 
dndn 
ea 


E140 
E100 
E180 
E040 
E000 
E080 
E148 
E108 
EIS 
E048 
E008 
E088 
E158 
ENS 
E198 
E058 
0/8 
E098 
E150 
E10 
E190 
£050 
G10 
E090 
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BCHG Type: The bit instructions take an immediate or data register 
operand and a data-alterable destination effective address, ‘The operation § 
is implicitly long for data register destinations and implicitly byte for 9 
destinations. 

behg Sea 

behg— dnyea 


behg 0140 
belr 0180 
bset 01c0 
bist 100 


CHK Type: These instructions take a data-source effective address and a dat 
register destination. Source and destination are implicitly word-sized for el 
muls, and mulu, Source is word sized, and destination is long for divs and divu, 


chk ea,dn 4180 
divs eadn 81C0 
diva eadn 80C0 
muls—eadn cco 
mulu cada coco 


IMP Type: These instructions require control-effective addresses. 


imp ca 480 
jsr ea 4580 
ea ean 410 
pea ea 4840, 


MOVE Type: Move instructions take any source effective address to data-alter- 
uable destinalion effective addiesses, bul byte moves fom addiess registers are 
forbidden. When the destination is the condition-code or status register, the 
source must be a data effective address and the instruction size is implicitly, 
byte or word respectively. When the status register is the source the destination 
must be a data-alterable effective address. When the user stack pointer is an 
operand, the other operand is an address register and the instruction size is im- 
plicitly long. 
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move ea,ea 3000 
move.b  ea,ea 1000 
move.l ea,ea 2000 
move eacer «440. 
move east 46CO 
move —srea 40co 
move anusp — 4E60 
move span 4E68 


MOVEM Types These instructions take two forms: an immediate-register mask 
source with a control or predecrement destination, or a control or postincrement 

uree with an immediate-register mask destination. The bit ordering in 
register masks is the programmer's responsibility. 


movem $n.ea 4880 
movem —¢a,$n 4c80 
movem.l $n,2a 48Cco 
movem,] ea,$n 4cco 


MOVEP Type: The move-peripheral instruction uses data register and address 
register indirect with displacement operands. 


movep ean),dn_ 0108 
movep dng(an) 0188 
movepl e(an),dn 0148 
movep.l dn(an) 01C8 


Miscellaneous Tastructions; the remai 
which is self explanatory. Mnemonics with ".s" 


ing instructions have operand syntax 
are short displacements, within 


+127 or -128 bytes (nor words). 


bee 1 6400 
bee.s 1 6400 
bes 1 6500 
bes. 1 6500 
beq 1 6700 
beast 6700 
bge 1 6C00 
bees 600 
bgt 1 6E00 
bets 1 ‘6E00 
bhi 1 6200 
bhis it: 6200 
bhs 6400 
thes 6400 
ble 1 6F00 
bles 1 6F00 
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dbgt 
dbhi 
dbhs 
dble 
dbio 
dbls 
dbit 
bmi 
dbne 
dbpt 
dbra 
dbt 
dbve 
dbvs 
exe 
ext 
ext 
link 


1 
1 
i 
1 
1 
1 
1 
1 
1 
1 
af 
1 
1 
1 
1 
1 
1 
1 
1 


1 
(an)+(an)+ 
(an}s,(an)+ 
(an)+,(an)+ 
dnl 

ani 

anil 

dat 

dn 

dnl 

dnl 

dal 

dal 

dnl 

dnl 

dnl 

an 

dn.l 

dnl 

an 

dnl 

dnt 

dnt 

rman 

an 

dn 

ann 


6900 
B13, 
BIOS 
BIB 
S4C8 
55C8 
3708 
51C8 
5cc8 
SECB 
528 
54C8 
5FC8 
53C8 
53C8 
SDC8 
SBc8 
36C8 
5ACB 
50C8 
30C8 
38C8 
5808 
C100 
4880 
48CO 
450 
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moveq $ndn 7000 
nop 4E71 
reset 4E70 
rte 4573 
tr 4E77 
rs 4E15 
stop Sn 4572 
swap dn 4840 
wap $a 4E40 
trapy 4576 
valk = an 4E58 
See Also 


as68toas, ce, epp, commands, drtomw, Id 


Diagnosties 
as reports errors on the standard error device. It gives a one-letter error code, 
the line number, the input file (if more than ane specified), and a symbol where 
appropriate, See the section on Errors, presented earlier in this manual, for in- 
terpretation of error codes, 


as68toas—Command 


Convert DRI assembler to Mark Williams assembler 
as6Btoas <oldfile.asm >newfile.s 


as6Btoas converts files of 68000 assembly language from the DRI dialect into 
the Mark Williams dialect. Tt accepts DRI-style instructions from the standard 
input device (normally the keyboard), and produces Mark Williams-style in 
structions on the standard ourput (normally the screen). If it cannot handle a 
given instruction, it will notify you via the standard error (normally the screen), 
As shown above, files can be converted automatically under the microshell by 
using the redirection operators ‘<' and ‘>’. Thus, to convert the file foo.asm, 
which is written in DRI-style assembly language, into a file of Mark Williams- 
style assembly language, called foa.s, simply type: 
as8Btoss <fa0.s0m 950.8 


Note that files of Mark Williams-style assembly language must have the suffix 
‘Si otherwise, they will not be accepted by the assembler as, 

See Also 

as, commands, drtomw, TOS 


ASCII—~Definition 


ASCII is an acronym for the American Standard Code for Information Inter- 
change. It is a table of seven-bit binary numbers that encode the letters of the 
alphabet, numerals, punctuation, and the most commonly used contral sequen— 
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Lexicon, 
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ces for printers and terminals, ASCII codes are used on all microcomputers sold 
in the United States. 


The following table gives 


the ASCIT characters in octal, decimal, and 


hexadecimal numbers, their definitions, and expands abbreviations where 


necessary. 
000 0 

ool 1 

0022 

003 3 

0044 

0055 

006 6 

0077 

O10 8 

ol 9 

012 10 
01300 
01412 
01s 13 
016 14 
01715 
02016 
02117 
02218 
02319 
024-20 
023 
026-22. 
027-23 
030 24 
O31 35 
0322 

03327 
034-28 
03529 
036-30 
03731 
040 32 
041 33 
042 34 
04335 
044 36 
ods 37 
046 38 
04739 


ox00 
Oxd) 
Oxd2 
0x03 
0x04 
0x5 
0x06 
0x07 
Ox08 
0x09 
OxdA 
0x0B 
Ox0C 
Ox0D 
0x0 
Ox0F 
Ox10 
Oxll 
x12 
0x13 
Ox 
Ox15, 
0x16 
Ox17 
Ox18 
Ox19 
OxtA 
Ox1B 
OxIC 
Ox1D 
OxIE 
OIF 
0x20 
0x21 
0322 
0x23 
0x24 
0325 
0326 
0327 


NUL 
SOH 
STX 
FIX 
EOT 
ENQ 


<ctrl-@> 
<ctrl-A> 
‘ctrl-B> 
<ctrl-C> 
<etrl-D> 
<ctrl-E> 
<ctrl-F> 
<ctrl-G> 
<ctrl-H> 
<ctel-I> 
<ctrl-J> 
setrl-K> 
etrl-L> 
<ctrl-M> 
‘<etrl-N> 
<etrl-O> 
<ctrl-P> 
<ctrl-Q> 
<ctrl-R> 
<ctrl-S> 
<etrl-T> 
etrl-U> 
<ctrl-V> 
etl W> 
<ctrl-X> 
sectrl-Y> 
‘ctrl-Z> 
<etrl-I> 
<ctrl-\> 
sctrl-}> 
actrl=*> 
<ctrl-_> 
Space 


NUL character 

Start of header 

Start of text 

End of text 

rad of transmission 
Enquiry 

Positive acknowledgement 
Bell 

Backspace 

Horizontal tab 

Line feed 

Vertical tab 

Form feed 

Carriage return 

Shift out 

Shift in 

‘Data link escape 

Device control } (XON) 
Device control 2 (tape on) 
Device control 3 (XOFF) 
Device control 4 (tape off) 
Nogative acknowledgement 
Synchronize 

Tad of transmission block 
Cancel 

End of medium 
Substitute 

Escape 

Form separator 

Group separator 

Record separator 

Unit separator 


Exclamation point 
Quotation mark 
Pound sign 

Dollar sign 
Percent sign 
Ampersand 
‘Apostrophe 
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(Left parenthesis 
) Right parenthesis 
* Asterisk 
+ Plussign 

Comma 

Hyphen (minus sign) 
Period 

‘Virgule (slash) 


Werner: 


Colon 
Semicoton 

Less-than symbol (left angle bracket) 
Equal sign 

Greater-than symbol (right angle bracket) 
Question mark 

Atsign 
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0126 
0127 
0130 
0131 
0132 
0133 
0134 
0135, 
0136 
0137 
0140 
O14 
0142 
0143 
14g 
0145 
0146 
0147 
0150 
0151 
0152 
0153 
o1s4 
0155, 
0156 
0157 
0160 
0161 
0162 
0163, 
o164 
0165 
0166 
0167 
0170 
0171 
0172 
0173, 
0174 
O75 
0176 
0177 


86 
87 
88 
89 
90 
a1 
92 
93 
94 
95 
96 
97 
98 
99 
100 
101 
102 
103, 
104 
105 
106 
107 
108 
109 
10 
i 
112 
113 
114 
115 
116 
117 
118 
119 
120 
121 
122 
123 
124 
125 
126 
7 


See Also 


string 


0x56 
0x57 
0x58 
0x59. 
OSA 
OxSB 
Ox5C 
OxSD 
OxSE 
OF 
0x60 
0x61 
0x62 
0x63, 
0x64 
0x65, 
0x66 
0x67 
0x68, 
0x69 
Ox6A 
Ox6B 
Ox6C 
Ox6D 
Ox6E 
Ox6F 
0x70 
Ox71 
0x72 
0x73 
x74 
0x75 
0x76 
0x77 
0x78 
0x79. 
Ox7A 
Ox7B 
Ox7C 
Ox7D 
OxTE 
Ox7F 
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Left bracket (left square bracket) 
Backslash 

Right bracket (right square bracket) 
Circumflex 

Underscore 

Grave 


Left brace (left curly bracket) 
Vertical bar 

Right brace (right curly bracket) 
Tilde 

Delete 
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ime—Time function (libe.a/etime) 
‘Convert time structure to ASCII string, 
include <time.h> 
char *asetime(emp) tm_t *emps 


aseti 


asctime takes the data found in ¢mp, and turns it into an ASCII string that can 
be read by humans. (mp is declared to be of the type tm_t, which is a siructure 
defined in the header file time,h, This structure must first be initialized by 
cither gmtime or localtime before it can be used by asctime. For a further d 
cussion of tm_t, see the entry for time. 


Example 

‘The following exemple demonstrates the functions asetime, etime, gmtime, 
iocaltime, and time, and shows the effect of the environmental variable 
TIMEZONE. For a discussion of the variable time_t, see the entry for time. 


include <tinesh> 
main) € 
inet tinenunbers 
tae *inestruct; 


tinec&e fimenunberd 
printfcwism, etimecBtimeramber)); 


tinestruct = gat ime¢tinenunber); 
printfcwis, asctineCtinestruct)); 


local time(ttinenunber); 
esetineceineotsuct)); 


5 


The following gives an “optimized” form of the above program. 1t shows more 
early how return values can be passed as arguments, and how nesting can in 
crease the work done by each line of code. 


#ioclude <tinesh> 
ming € 
tint 
tinetaea? 
prinefcitst, ctimecat)): 
printfCrds", asctine¢gmtime 2t))); 
Printfrist, asctine( local timec&t))9; 


5 


See Also 
time 
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asin—Mathematics function (libm.a/asin) 


assert—Debugging macro 


88 


Notes 
asctime returns a pointer to a statically allocated date area that is overwritten § 
successive calls, 


Calculate inverse sine 
#include <math.h> 
double asin(arg) double arg; 


asin calculates the inverse sin of arg, which must be in the range [-1., 1.]. 
result will be in the range [-PT/2, PI/2]. 


Example 

For an example of this function, see the entry for acos. 
See Also 

mathematics library 


Diagnostics 
‘Out-of-range arguments set ereno 10 EDOM and return 0. 


Check assertion at run time 
#include <asserth> 
assert(condition) 


assert checks the value of the given condition. If the condition is false (0), assert 
prints an error message and exits. assert should be used to decect situations that 
are expected never to happen, Note that the -DNDEBUG argument to ce 
disables all checking of assertions. 


Example 
#inelude <assert.t> 
ping) ¢ 
inta= ty 
int b 


assert( @b ); 
5) 
See Also 
#assert, assert.h, cc 


Diagnosties 

assert prints assert(condition) failed when condition is not true, Because assert 
is a macro that uses printf, it exoands into an illegal C statement if cowdition 
\cludes quotation marks (*"), It also cannot be used in an expression. 
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assert.h—Header file 
Text of assert message 
include <assert.h> 


assert.h is the header file that contains the assert macro definition. 


See Also 
assert, header file 


sassert—Definition 
Check assertion at compile time 
#assert expression 


The Mark Williams C preprocessor cpp, in addition to the directives mentioned 
in The C Programming Language, recognizes the #assert directive. It has the 
form: 


dassert constant _expression 


The preprocessor evaluates the constant expression. If it is false (zero), cpp 
prints a diagnostic message. The condition being tested must be an expression 
that involves constants of the form acceptable to the preprocessor’s #if func— 
tion. This tool should be used to ensure that variables in complex preprocessor 
code are correct throughout the program, 


Example 
¥ the line 


Hassert St2e < 80 


is included in a program, the assertion will succeed if SIZE js less than 80, and 
fail if it is 80 or more. 
See Also 
pp 
The C Programming Language, page 86 
Diagnostics 
‘The failure of an #assert causes the message 
Preprocessor assertion faflure 


to appear on the standard error device; however, failure of an #assert direct 
does not terminate compilation, 


atan—Mathematics function 
Calculate inverse tangent 
#include <math.h> 


ym.a/atan) 
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double atan(arg) double arg; 


atan calculates the inverse tangent. arg may be any real number, The resul 
will be in the range [-PI/2, PI/2}. 

Example 

For an example of this function, see the entry for acos. 


See Also 
errno, mathematics library 


atan2—Mathematics function (libm.a/atan2) 


Calculate inverse tangent 
double atan2(num, den) double num, dem; 


atan2 calculates the inverse tangent of the quotient of its arguments mum/den, 
num and den may be any real numbers. The result will be in the range [-PI, 
PI), The sine of the result will have the same sign as num, and the cosine wi 
have the same sign as den. 

Example 

For an example of this function, see the entry for acos. 

See Also 

errno, mathematics library 


atof—General function (libe.a/atof) 
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Convert ASCIT strings to Floating point 
double atof(string) char * string: 


atof converts the argument string to a binary representation of a double-preci~ 
sion floating point number. The argument string must be the ASCII representa~ 
tion of a floating-point number. It can contain a leading sign, any number of 
decimal digits, and one decimal point. It can be terminated with an exponent, 
which consists of an ‘e’ or ‘E? and followed by an optional leading sign and any 
number of decimal digits. atof ignores leading blanks and tabs; it stops scan~ 
ning when it encounters any unrecognized character. 


Example 
For example of this function, see the entry for acos. 


See Also 
atoi, atol, float, long, printf, scant 


Notes 
No overflow checks are performed. atof returns 0 if it receives a string it can— 
not interpret. 


att 


atol 


atol-atol 


: General Function (libe.a/atoi) 
Convert ASCII strings to integers 
int atol( string) char * string; 


atol converts the argument siring to the binary representation of an integer. 
siring may contain @ leading sign and any number of decimal digits. atoi ig- 
nores leading blanks and tabs; it stops scanning when it encounters any non- 
‘numeral other than the leading sign, and returns the resulting int. 


Example 
The following demonstrates atol, It takes a string typed at the terminal, turns it 
into an integer, then prints that integer on the screen, To exit, type <ctrl-C>. 


maint) € 
extern char Hgsts()s 
extern int ati; 
char string 64) 
forts) € 
Dprtncfoeneer nunerte ste 
if(gets(string)) 
Print fcrad\n, atof stringy): 


alse 
breaks 
> 
3 
See Also 
atof, atol, int, printf, seanf 


Notes 
No overflow checks are performed, atoi returns 0 if it receives a string it can- 
not interpret 


General function (libe.a/atol) 
Convert ASCIT strings to long integers 
long atol(string) char “strings 


atol converts the argument string to a binary representation of a long. string 
may contain a leading sign (but no trailing sign) and any number of decimal 
digits, atol ignores leading blanks and tabs; it stops scanning when it en- 
counters any non-numeral other than the leading sign, and returns the resulting 
Tong. 


Example 
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natn € 
‘extern char *gets0; 
extern Long atol(; 

char stringt@4l 

forts) € 

printf(enter nuneric-steing: * 

ff(gets(string)) 
print oneta\n 


atoleteine)); 


else 
break: 


> 

See Also 

atof, atol, float, long, printf, scant 
Notes 


No overflow checks are performed. atol returns 0 if it receives a string it can— 
not interpret. 


auto—Definition 


auto is an abbreviation for an automatic variable. This is a variable that applies, 
only to the function that invokes it, and vanishes when the functions exits. The 
Word auto is a C keyword, and may not be used to name any function, macro, 
or variable. 


See Also 
extern, Keywords, stack, static, storage class 
The C Programming Language, page 28 


\auto—Definition 
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\auto is a directory that is scanned by TOS when it boots. TOS looks for this 
directory on the disk in drive A:. If it is present, TOS executes all of the files 
Stored there that have the suffix .pre, in the order in which they appear. This 
js useful for automatically setting up such tools as RAM disks. 


Note that when TOS executes the programs in \auto, the AES and VDI have not 
yet been initialized, so no GEM applications can be run, The current directory 
Bf the programs run from \auto is the root of the boot disk, If Line A 
functions are used, they must provide their own coutrl, intin, and intout arrays: 
You can place msh.prg into \auto and enter it automatically when you boot 
your system; however, subsequent attempts to run any GEM application 
through msh generates effects that are unpredictable and usually unwelcome 
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Example 
The following example shows a few things that you can do in 2 program that is 
placed in \auto. It cemonstrates the functions Cursconf, Iorec, Kbrate, linea0, 
Ptermres, Rsconf, Setprt, stime, and time, the global variable " stksize, and the 
header Tiles basepage-h and xbios.h. 


Hirelude <Uineo.h> 
Hireluse <osbind. te 
#inslude <time.h> 
include <besepege. te 
insluse <xbfos. ho 


long _stksize = 256; (* We need very Little stack for this */ 
rained € 
in 


+ nits Linead(): inftiatize la date for graphies 
+ Initializing these pointers allows lines graphics in \auto\*-pra 
” 


« 
static int intinti281, intouttt2a, ptsint1281, ptsout (126): 
static int teontrl £6 
Tnead0d; 

INTIN = iating 


stine(: set initial system tine From the keyboard clack 
* vimec) reads the keyboard clack, stime() wiLl set the GEM-COS tine 


"7 
« 
tine_t ty 
time); 
stine(tt); 
¥ 
re 


* init: Torec<: resize the input/output suffers 
* increasing the buffer sizes may or may not be necessary 

7 ft depends on how fast the buffers are filled and enptied 
* 


« 


register struct fores ip; 
static char auxin(026), auxeut (10261, midi c102¢), kbdt1026); 
static struct fore tmp'= € 0, 1024, 0, 0, 256, 768 7 
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ip = loree¢to AUK); tep.io buff = auxin; *ip = tmp: 
ip t= 1p tmpeto buff = autout; tip = tmp; 

ip = Torecc10.MiD); tap.fo buff = midi; “ip = tmp; 

Sp = Torec10_K8D); tmp.fo_buff = kbd; “1p = tap; 


r 
© init: Rsconf()r configure r3232 port 
= Gat the default baud rate ond contral protocol for the serial port 
# 

Peconf 2S #9800, RS_XONWOFF, 


ope 


/* init: setpeto: set printer configuration */ 
‘SetprecPR SERIAL |PR_EPSON|PR_MONO|PR_MATRIXD: 

on 

= nits curscenf(): set cursor configuration 

= Thie slows the blink donn to half the normal speed 

” 


cursconf (cz seT, (int)Curscont¢cc_oeT, 0)*2); 
% Init: Kbrete(): set keyboard repeat configuration 
+ Again, simply slow 1t down a bit 
” 
« 
register int start, delay; 
start = Korate¢-1, -1);, 
delay = stert & Oxtf; 
start >= 8; 


delay * 43 
Kerate(start, delay); 


” 
= nits terminate and stay resident, so the buffers we assigned de not 
* get clobbered by the next progran that runs 
” 

Prermres(se->p_hitps-8°->p_lovtea, 0); 

> 
See Also 

TOS 


aux—TOS device 
TOS logical device for serial port auxiliary device 


TOS gives names to its logical devices. Mark Williams C uses these names, 10 
is the 


allow the STDIO library routines to access these devices via TOS, aux: 


94 


aux: 


logical device for the the serial port auxiliary device. 
Example 


virelude <stdio.h> 
rain(ae 
FILE *fp, *fopenc); 
if (Cf = Fopenttauxe™, my) = MULL 
fprint#(fp, "aux: enabled.\n); 
else print#éaur: cannot open. Mn"; 


> 
See Also 

con:, prn:, Rsconf 

Notes 

aux: may be spelled aux: or AUX:. 
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backspace—Definition 


basepage.h—Header file 
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‘Mark Williams C recognizes the literal character “\b’ for the ASCII spag 
character BS (cotal 010). ‘This character may be used as @ character constant, 
in a string constant, like the other character corstants: ‘\a’, whic rings 

‘audible bell on the terminal; ‘\P, to pass a formfoed command to the printe 
‘\P, for a carriage return; ‘\t, for a horizontal tab character; and ‘\v’, the verti 
cal tab character, 


See Also 
‘ASCIL, character constant 


‘TOS header file 
#include <basepage.h> 


hasepage.h is « header file that defines the GEM base page structure. Its text 
as follows: 


ifndef BASEPAGE # 
def ine BASEPACEH 


typedef struct € 
ona /* Lou transient program sree */ 
Leng 7° #igh transient program area */ 
ong 7* Text segnent base */ 
long 7 Text segment length */ 
Long Length base */ 
ong Length lenge */ 
tong at (7 Bas segnent base */ 
long pblens J abe coavent Length */ 
long pifxxO 133; /* FALL aren one */ 
long envy 7 Enviroment string pointer */ 
long pofuxt (200; # FILL block two #7 
char plendLint'28i;  /* Conard Line */ 
2) BASEPAGE; 


extern RASEPAGE start; 
fidefine BP CB stertl-12) 
endif 

See Also 

header file, TOS 


Reoeive a character 
+#include <osbind.h> 
#include <bios.h> 
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Beonin 


jong Beonin(handle) int hemalte; 


Beonin receives a character fram a peripheral device, handle is an integer that 
incicates which device is being read, as follows: 
0 prm: (the fine printer) 
aux: (the auxiliary serial port) 
the console) 
the MIDI port 
the intelligent keyboard (output only) 
the raw screen (output only) 


When Beonin reads from eon:, it returas the key's raw scan code in the low byte 
of the high word and either an ASCH character or zero in the low byte of the 
low word, depending upon whether the key typed generates an ASCII character 
or not; when it is reading from aux:, it returns the character in the low byte of 
the low word, 


For a table of keyboard scan codes, see the entry for keyboard. Note, too, that 
this function is unaffected by redirection of either con: or aux:, 


Example 


This example emulates a simple dumb terminal, It demonstrates the functions 
Beonin, Bonout, Boonstat, Beostat, and Pterm0, 


Binclude <osbind. to 
Hinslude <bies.h> 


nainc 
« 
register long ep 
a 
(Beoneeati8e_£0N9) © 
© = Beonin¢8C_CON); 


for ¢ 


iF inte 


if (e == Ke_u0o) 
break 
Sconcut(8e_CoN, "\a! 
d else ¢ 


While (Beostat(Bc_ALX) == 0) 


Beonout (BC ALK, Cintded: 
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Beonout-Beonstat 


FF (teanatat(8C_AVO) € 
fc = BeoningBC_AULD: 
Beonaut(ac_cOw, Cint}edz 
y 
> 
Penmaes 
d 


See Also 
‘ux, Beonout, Beonstat, Beostat, bios, cont, keyboard, TOS 


Beonout—bios function 3 (osbind.h) 


‘Send a character to a peripheral device 

#include <osbind.h> 

#include <bios.h> 

Joid Beonaut(indle. character) int handle, character; 
Beonout sends characters to an output device. handle is an integer that in—” 
dicates which device to send characters, as follows: 

: (the Hine printer) 

(the auxiliary serial port) 

con: (the console) 

the MIDI port 

the intelligent keyboard (output only) 
the raw screen (output only) 


weunes 


character is the character being output, which is encoded in the lowor eight bits 
charset aieger.  Beonout returns nothing. This function is unaffected by” 
redirection of the logical devices con: or aux:. 


If handle is set to five, characters are displayed on the screen as with device 
wae'S but control characters are not interpreted, This allows the dispiey, of 
graphics characters from the Atari character set, in the range of one through 31. 
Example 

For an example of this funetion, see the entry for Beonin. 

See Also 

Beonin, Beorstat, Beostat, bios, TOS 


Reonstat—bios function 1 (osbind-h) 


Return the input status of a peripheral device 
include <osbind.h> 

#include <bios.n> 

long Beonstat(device) int devices 
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Beostat-bios.h 


Beonstat reads the input status of the specified peripheral device. device is an 
integer that encodes the Beostat of the desired device, as follows: 

prn: (the line printer) 

aux; (the auxiliary serial port) 

con: (the console) 

the MIDI port 

the intelligent keyboard (output only) 

the raw screen (output only) 


Beonstat returns -1 if at least one character is ready to be handled, and 0 if no 
characters are ready. This function is unaffected by redirection. 


Example 
For an example of this function, see the entry for Beoain. 


See Also 
Bonin, Bconout, Beostat, bios, TOS 


eostat—bios function 8 (osbind.h) 
Read the output status of a peripheral device 
#include <osbind.h> 
#include <bios.h> 
long Beostat(handie) int handle; 
Beostat reads the output status of a peripheral device, handle is a number that 
indicates the device to be checked, as follows: 
prn: (the line printer) 
aux: (the auxiliary serial port) 
‘con: (the console) 
the MIDI port 
the intelligent keyboard (output only) 
the raw screen (output caly) 


Beostat returns -1 if the device is ready, 0 if it is not. This function is unaf~ 
fected by redirection. 


Example 
For an example of this function, see the entry for Beonin. 


bios.h—Header file 
#inelude <bios,h> 
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bios.h is @ header file that includes all constants and structures used by the: 
GEM-DOS bios functions, For a list of these functions, see the entry for bios, 
See Also 

bios, header file, TOS, xbios.h 


bies—TOS function 
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Call an input/output routine in the TOS BIOS 
#include <osbind.h> 
extern long bios(n, fl, (2... fn)s 


bios allows you to call an input/output Function direcily in the Atari BIOS. It 
works by building a stack frame and executing trap no. 13. Unless. the: 
NOTRAP option is used when compiling a program, the instruction jsr 
is replaced by a trap no. 13 instruction. 


nis the number of the function, and f7 through fn are the parameters to be 
sed with the routine, In most circumstances, it is unnecessary to call bies, for 
the header file osbind.h defines @ number of functions that use it directly. All 
‘Structures and constants used by these functions are contained in the header file 
bios.h. 


‘The following Functions call bios to deal with the peripheral devices: 


Beonia receive a character 
Beonout output a character 
Beonstat return input status of device 
Beostat return output status of device 
Devmap return map of logical drives 
Getbpb return pointer to BIOS parameter black 
Getmpb copy memory parameter block 
Getshift gel/set status for shift/alt/contral keys 
Mediach check if medium has been changed 
Rwabs read/write a disk drive 
Setexc set an exception vector 
Tickcal return system timer’s calibration 

See Also 

osbind.h, TOS 

Notes 


No bios function checks for incorrect device numbers. Passing a bogus device 
‘number to a routine will crash the system, 


Note that the Ateri BIOS will support up to three recursive calls at any one 
time, Using more than three will cause the system to crash, 


Note that all bios functions are unbuffered. Combining them with buffered 
routines, such as those in the STDIO library, will lead at best to unpredictable 
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BIOS-bit map 


results, 


BIOS- Definition 
BIOS is an acronym for basic input/output system. In most machines, the BIOS 
consists of a routine carried in the read-only memory (ROM). 


See Also 
bios, STDIO 


Bioskeys—xbios function 24 (osbind.h) 
Reset the keyboard to its default 
#include <osbind.h> 

include <xbios,h> 

void Bioskeys() 


Bioskeys resets 
does whatever changes were made 
Example 


include <osbiind. > 
sain() € 
Bioakeys¢; 


keyboard to its default settings, and returns nothing. It un- 
ith the function Keytbl. 


) 


See Also 
Keytbl, TOS, xbios 


bit—Definition 

bit is an abbreviation for binary digit. It is the basic unit of data processing, 
the computer analogue of Democrites’ atoms, A bit can have a value of either 
zero of one, and can be concatenated into strings. A bit can be used either as a 
placeholder to construct a number with an absolute value, or as a flag whose 
value as a particular meaning under specially defined circumstances. In the 
former use, a string of bits builds an integer. Tn the latter use, a string of bits 
Forms a map, in which each bit has a meaning beyond its numeric value. 


See Also 
bit map, byte, integer, nybble 


bit map—Definition 
‘A bit map is a string of bits in which each bit has a symbolic, rather than 
numeric. value. For example, the Drvmap function returns a 16-bit map of the 
active drives on the Atari ST,’ The bits indicate which of 16 possible disk drives 
is available, with bit 0 (i.e., 1<<0) corresponding to drive A, bit | to drive B, 
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bombs-boot 


bombs—Definition [ 


boot—Definition 
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ete, 

See Also 

bit, byte 

The C Programming Language, page 136 
Notes . 
© permits the manipulation of bits within a byte through the use of bit field 


routines. However, programs that use bit fields often run more slowly than’ 
those that use masking and shifting. 


When a program goes seriously wrong on the Atari ST, TOS takes the following” 
default actio 


1, Itstores a description of the program's state in « buffer in low memory. 


2. It displays one or more “cherry bombs” on the screen; persons with older 
versions of the operating system may see little “mushroom clouds" in- 
stead. ‘The number of bombs seen is equal to the number of the processor 
exception. 


3. TOS attempts to terminate the program and continue processing. 


‘You use the debvgger db to display the program state saved in low memory by 
TOS. Use the following commands: 


db-k enter db 


© display contents of registers 
if print type of fault 
4 quit 


This prints the processor registers at the time of the fault and identifins the” 
fault. The exceptions that occur on the 68000 processor are listed in the header 
file signal.h. 


See Also 
db, signal-h, TOS 


Boot is an abbreviation for bootstrapping procedure; this refers to the procedure 
by which a computer loads certain elementary routines to organize and test 
memory, and initialize peripheral devices. The term warm hoot is used with 
some operating systems to tefer to the second-stage bootstrapping procedure, 
which is done simply to restore portions of the operating system that may have 
been overlaid by user code during the operation of a program, or that 
reinitializes the system state without going through the entire boot provedure. 
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buffer-byte ordering 


see Also 
exit 

Notes 

‘YOS does not warm boot on program termination. 


putfer—Definition 
‘A buffer is 2 portion of memory reserved for a particular purpose. In the con- 
text of C, a buffer most often is an area set aside to hold data for a peripheral 
device; often, although not always, this involves setting aside a portion of the 
arena with malloc or its related Functions. 


Many operating systems automatically place data from a peripheral device into 
x buffer, Buffers normally can be cleared with fflush, by pressing the carriage 
return key on routines that perform input, or by sending a newline character on 
routines that perform output, The function close, which closes a file, will flush 
all buffers; exit calls close by default. 


Note that combining 
functions on the same 
predictable. 


On the Atari ST, all STDIO routines use buffering by default. stdin end stdout 
stderr is not, Buffering can be turned off with the function setbuf. All Atari 
functions that perform 1/0 are not buffered. 

See Also 


arena, array, Cconrs, Cconws, fflush, malloc, setbuf, STDIO. 
The C Programming Language, page 173 


fone program unbuffered and and buffered 1/0 
or device may produce results that are, at best, un- 


byte-Definition 
A byte is a group of eight bits, which often is used to encode a character. Note 
that “byte” is not a legitimate term of data organization in C. Data types are 
defined as multiples of the data type char; what a char is defined to be depends 
on the hardware, Although a char is often defined as being eight bits long, the 
same as a byte, this definition is not universal. 
See Also 
bit, char, data formats, nybble 


byte ordering—Definition 
Byte ordering is the order in which a given machine stores successive bytes of a 
multibyte data item, The following example displays a few simple examples of 
byte ordering: 
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byte ordering Lexi 
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rained © 
Union € 
char tA 
int £123 
tong 15 
> 
ut = ox12845678U; 


printf cre x te Hen, u-bOO2, ube}, wbi2l, Ub); 
Brinton Beat, FEO), UAL; 
prinerounts\nl, 


> 
When run on a PDP-1] under the COHERENT operating system, it gives the 
following results: 

34.12 78 56 

ye3t 5678 

12365678 
When run on the 68000 under TOS or on the 28000 under COHERENT, it gives, 
the following results: 

12 34 56 78 

1234 5678 

12805678 
When run on the i8086 under UDI or COHERENT, it gives the following 
results; 

7a $6 36 12 


5678 1236 
52545678 


As can be sccn, the order of the bytes differs between the machines. 


See Also 
canon.h, data formats 
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C language 


Clanguage—Overview 
‘The following summarizes how Mark Williams C implements the C language. 
Identifiers. 
Characters allowed: A~Z, a-x,_, 
Compiler end linker are case sensitive. 
Number of significant characters in a variable name: 
at compile time: | 128 
at fink time: 16 
identifier tag appended by compiler: __at end of identifier 


Reserved identifiers (keywords): 


alien entry return 
auto extern 

break float 

case for 

char gote 

continue if 

default int 

do Jong 

double readonly unsigned 
else register while 


The keyword entry is not implemented. The proposed ANSI standard for C 
adds const, signed, and volatile to the above set, and deletes entry and readonly. 
‘Mark Williams C reserves the keywords readonly and alien, but these are not 
implemented on the 68000. 


Data formats (in bits) 


char. 8 
double: 64 
float: 32 

c 16 
long: 32 
pointer: 32 
short: 16 
unsigned char: 8 
unsigned short: 16 
unsigned int: 16 
unsigned long 32 
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float format: 
DECVAX floating point format, 
1 sign bit 
8-bit exponent 
24-bit normalized mantissa with hidden bit 
DECVAX double format 
Same as float, but with 56 bits of mantissa 
Reserved values: 
+ infinity, -0 
All floating-point operations arc done as doubles 


Limits: 
Maximum bitfield size: 16 bits 
Maximum number of cases in a switch: no formal limit 
Maximum block nesting depth: no formal timit 
‘Maximum parentheses nesting depth: no formal limit 
‘Maximum structure size: no formal imit 
Maximum array size: 64 kilobytes 


Preprocessor instructions: 
Hassert — #ifdef 
adefine — #ifndef 


#else #include 
#endif — #line 
file #undef 
if 


Structure name-spaces: 
‘Supports both Berkeley and Kernighan and Ritchie conventions 
for structure in union. 


Register variables: 
Five available for ints or longs 
‘Three available for pointers 


Function linkage: 

Return values for chars, ints, longs, or pointers in dO. 

Return values for doubles in dO and dl 

Pointers to returned structures in d0, copied to destination by caller 

Parameters pushed on stack in reverse order, chars and shorts pushed 
as words, longs and pointers pushed as longs, structures 
copied onto stack 

Caller is responsible for clearing parameters off stack 

Stack frame linkage is done through 26 
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C language 


Register usage: 
dO, dl: Scratch data and function return values 
d2: Scratch data 
43, d4, d5, 46, d7: Register variables for longs and ints 
a0, al, a2: Scratch addresses 
a3, a4, a5: Register pointers for any type or structure 
a6: Call frame linkage pointer 
a7: Stack pointer 


Special features aid optimizations: 
+ By default, the compiler makes the following substitutions: 


sr gendos_ trap $1 
sr micrortx trap $5 
Isr bios_ trap $13 
Jer xbios_ trap $14 


This reduces the overhead for system calls and makes the code ceentvant 
{although the system itself may not be). Turn off this feature with the 
option = VNOTRAP. 


Branch optimization is performed: this uses the smallest branch instruc 
tion for the required range 


* Unreached code is eliminated, 
+ Duplicate instruction sequences are removed. 
Jumps to jumps are eliminated, 
* — Cross—jumps are eliminated. This changes code like this: 
nove 8, 8 
bra LABEL 
LABELO: move €, b 
‘bra LABEL 
UBELt:pove 8, 
‘bra LABELS 


LiweL2emove f, 
bra LABELS 


to: 


move a, & 
rove by d 
bra LABELS 

LABELOEMOve €, 
move fd 
bra LABELS 
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ccabs-calling conventions 


See Also 
byte ordering, data formats, data types, declarations, keywords, Lexicon, 
memory allocation 


cabs—Mathematics function (Iibm.a/cabs) 
Complex absolute value function 
#include <math.h> 
double cabs(z) struet { double r, i) 2 


cabs computes the atsolute value, of modulus, of its complex argument =. The 
absolute value of a complex number is the length of the hypotenuse of a right 
triangle whose sides are given by the real part r and the imaginary part i, The 
result is the square rool of the sum of the squares of the parts. 


Example 
For an example of this function, see the entry for acos. 


See Also 
hypot, mathematies library 


calling conventions—Definition 
‘This entry discusses the Mark Williams C function calling conventions. This in— 
formation is helpful to users who wish to interface C programs with assembly 
language routines or with object code generated by other language processors. 
Programs that depend upon specific details of these calling conventions may not 
bbe portable to other processors or other C compilers. 


In general, Mark Williams C pushes arguments from right to left. Mark 
Williams C pushes function arguments as follows: 


char asa word 

short asa word 

int asa word 

long asa long word 

float _as.a pair of Jong words 


double as. pair of long words 
pointer asa Jong word 


“Word” in t 


instance means a 68000 (16-bit) word. 
‘An underbar *_' is eppended to the name of the function. ‘This makes assembly 


Inguage programmers append ‘_' to the names of their C callable functions, 
This is also used by the utility nm to choose the symtols printed with the -a 


option. 


‘An add, lea, or addq instruction after the call removes the arguments from the 
stick, 
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The C prologue executes a link to allocate space for automatics and saved 
registers. Because C functions may use registers a3 through a5 and 43 through 
7 for register variables, the C prologue saves used registers, and the C epilogue 
restores them. The C epilogue executes an untk before returning, 


Parameters and local variables in the called function are referenced as offsets 
from the (frame pointer) register, The stack-pointer register points below the 
local variable with the lowest address. 


Functions return values as follows: 


char in d0.W 
int in d0.W 
Jong, in d0.L 


float in dOand dl 
double in dO and dl 
pointer in dO.L 


Functions that return struct or union actually return a pointer to the struct or 
union, The code generated for the function call will move the result to its des- 
tination. 


C does not require that the number of arguments passed to a function be the 
same as the number of arguments specified in the function's declaration. 
Routines with a variable number of arguments are not uncommon. The two 
formatted 1/O routines in the standard library (printf and scanf) are, in fact, 
routines that take a variable number of arguments, 


Consider the following program as an example: 


tong #8, By © 
cher 2 
int b5 
long ¢: 
« 
return ({a * b) * 0); 


#2,b,094 


> 
When compiled with the -S option, it produces the following code: 
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2, 30 
10(06), 00 
(26), 


o 
12(86), 0 


vain, 
Link 26, 8 
mveq 1, 
reve. 40, -2¢36) 
neveq $2, 0 


reve 20, ~4¢36) 
moveq 83, 
rove.t 40, -8(36) 
rove.| — ~8(a6), a7) 
move ~6(26), G7 
ove. 

ist fi 

es 3, 37 

unt 36 


rs 


The symbols main and f have become main_ and f_. The automatic variables 
in main are addressed at negative offsets from a6: char a is located at -2(a6), 
int b at ~4(a6), and long c at -8(a6). A byte of unused storage follows a so that 
b occurs on an even address. main pushes c, then b, then sign extends a and 
pushes the resulting word. The arguments in f are addressed at positive offsets 
From a6: char a is located at 8(26), int b at 10(a6), and long ¢ at 12(a6). char ¢ 
ig treated as an int, The result expression is computed into d0.L, When f 
returns, main pops the arguments with an addq instruction. 


Inf after execution of the link, the stack appears as follows: 
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high 46 | <1786 = frame potter for F 


| pareneters 


The following function returns a structure: 


struct date ¢ 
int renth, day, years 
> todays 


struct date 

nnkdatm, 3, y) 

« 
struct date tap: 
tmpunenth=ny 
trpadey dr 
exp.year =¥i 
return tmp); 


naing) 
« 

today = widac3, 20, 859; 
> 


When this program translated into assembly language by compiling it with the 
-S option, the result is as follows: 


besd 
Lob today 


bike xb 
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shot 
ated kde 

ka 
bss 

ocar: 
bik xb 
shri 
Link 6, 8-8 
ove 8¢56), ~B(26) 
ove 10(28), -4(26) 
move 12¢28), -2¢a6) 
leo -6(36), at 
roves. ‘SL10001, 20 
move $6, d0 
rae (10002 

L093: 
nove. (at), (20) 
sg 
dg 

Lro002: 
cbf 0, 10008 
roves St 10001, 0 
untic 36 
rts 
salebl main 

Ae 26, $0 

poveq $85, 
ove @,'-(67) 
moveq «$20, 
move 0, -(a7) 
oveq «$3, 
neve 0, -4a7) 
Jer kde, 
add 86, a7 
roves. 0, at 
moves! Stoday_, 80 
move $6, 
bras 110004 
ov ct), (a0) 
ec 31, 28 
aoa st, al 
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calloc-carriage return 


bf 2, 19005 


Sve Also 
memory allocation 


ealloc—General function (libe.a/calloc) 
Allocate dynamic memory 
char *calloc(count, size) unsigned count, size; 


calloc is one of a set of routines that helps manage a program's arena, calloc 
calls malloc to obtain a block large enough to contain count items of size bytes 
each; it then initializes the block to zeroes and returns a pointer to it. Dynamic 
memory that is no longer needed can be returned to the free memory pool with 
the function free. 


See Also 
arena, free, Icalloc, Imalloc, Irealloc, malloc, notmem, realloc 


Diagnostics 

calloc returns NULL if insufficient memory is available. 

Notes , 

The related function Icalloc takes unsigned long arguments, and therefore can 
allocate memory blocks that are larger than 64 kilobytes. 


canon.h—Header file 
‘Canonical conversion for the 68000 
#include <canon.h> 


canon.h defines canonical conversion routines used for the 68000, to ensure that 
byte ordering is correct, 


See Also 
byte ordering 


carriage return—Definition 
‘Mark Williams C recognizes the literal character ‘\r' for the ASCII carriage 
return character CR (octal 015). This character ‘‘throws the carriage”, i.e, 
returns the cursor to the beginning of the line. The newline character ‘\n’ 
drops the cursor down to the next line, With the UNIX library routines, \n is a 
synonym for \n plus \r, TOS routines, such as Ceonws, need both characters 
explicitly. 
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eat-Cauxin 


\r may be used as a character constant or in a string constant, like the othe 
Sharacter constants: *\a', Which rings the audible bell on the terminal; *\b', to 
Backspace; ‘\P, to pass a formfeed command to the printer; ‘\t, for a horizontal 
tab; and *\v’, fora vertical tab. 


See Also 
‘ASCII, character constant 


eat Command 


Coneatenate Files 
cat [-u] [file 


cat copies each file to the standard output. A file specified by ‘~" indicates the: 
Standard input, If no file is specified, cat reads the standard input. 


‘The -u option makes the output unbuffered. Otherwise, cat buffers the output 
in units of the machine's disk block size. 


Note that <etrl-S> pauses the outputting of text, and <ctrl-Q> resumes output 
ting. 

See Also 

‘commands, msh 

Notes 

Redirecting the output of eat into one of its input files is an error, as the com= 
‘mand will never terminate. For example: 


will cause the system to loop, with the file out being read and written into until 
the file system runs out of space. 


Causin—gemdos function 3 (oshind-h) 
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Read a character from the serial port, 
+#include <osbind.h> 
Tong Cauxin() 


Causin reads a character from the serial port aus, and returns the character 
read, It is affected by redirection. 


Example 

Fhe Toltowing example creates a dumb terminal emulator that operates through 
the serial por. Tt demonstrates the macros Cauxin, Cauxis, Cauxos, Cauxoufy 
Choate, Ceonout, and Crawcin, You can exit from the program by typing <ettl= 
so Rin the example either From the GEM desktop, or with the tos command: 
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Caw 


include <osbind.b> 


pain © 
char cy 


iF (auxisea) 
Ceonoutte = Cauxin(d>; 
if (Beonised) € 
Ti (Ce = Craucin()) = 26) ¢ 


bre 
delse ¢ 

FF ¢Cauxos0) It 1f ready */ 

Cauxout ied: 7 send char */ 

else 7 Otherwise */ 

Ceonautt'\07!9; 7 ring bell */ 


5) 
> 


See Also 
certsg.0, gemdos, tos, TOS. 


Notes 

‘TOS defines handle 2 as being aux:, the serial port. The microshell msh norm- 
ally redirects handle 2 to another device; because Cauxin and its related 
functions can be redirected, any program that uses Cauxin, Cauxis, Cauxos, or 
Cauxout must be run directly from the GEM desktop, or run under the shell 
with the tos command, which re-redirects handle 2 to the aux: device. 


[An alternative is to use Beonin and its relatives instead of the Cauxin family 
when writing programs to be run under msh. 


Causis—gemdos function 18 (osbind.h) 
Check if characters are waiting at serial port 
#include <osbind,h> 
long Cauxis() 
Cauxis checks to see if characters are waiting to be read at the serial port, It 
returns -1 if there are characters waiting, and 0 if there are not. 
Example 
For an example of how to use this macro, see the entry for Cauxin, 
See Also 
gemdos, tos, TOS. 
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Cauxos—gemdas function 19 (osbind.h) 


Cauxout—gemdos function 4 (osbind.h) 


cc—Command 
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Notes 
‘This function must be compiled with the -VGEM option, and run either from 
the GEM desktop or with the tos command. 


‘Check if serial part is ready to receive characters 
‘include <osbind.h> 
Tong Cauxos() 


Causos checks the output status of the serial port. Cauxos returns -1 if the 
serial port is ready to send a character, and 0 if it is not. 


Example 

For an example of how to use this macro, see the entry for Cauxin, 
See Also 

gemdos, tos, TOS 

Notes 

“This function must be compiled with the -VGEM option, and run either fro 
the GEM desktop or with the tos command, 


Write a char to the serial port 
#include <osbind-b> 
void Cauxout(c) int o5 


Cauxout writes the character ¢ to the serial port, and returns nothing, 


Example 

Foi an example of how to use this macro, see the entry for Cauxin. 
See Also 

gemdos, tos, TOS 


Noles 
‘This function must be compiled with the -VGEM option, and run either from 
the GEM desktop or with the tos command, 


Compiler driver 
ce loptions| file . 


cc is the program that controls the compilation process. It guides files of source 
and object code through each phase of compilation and linking. ee has many 
options to assist in the compilation of C programs: in essence, however, all you” 
need to do to produce an executable file from your C program is type ¢¢ 


Mark Williams C 


followed by the name of file (or files) that holds your program, Tt chee! 
whether the file names you give it are reasonable, selects the right phase for 
each file, and performs other tasks that ease the compilation of your programs. 


ec assumes that each file name that ends in ,¢ or -h is a C program and proces 
ses it with the C compiler. It assumes that each file argument that ends in . is, 
an assembly-languzge program and processes it with the assembler as. It passes 
ail files with the suffixes .o or .a unchanged to the linker Id. 


‘The normal operation of the ce command is as follows. First, it compiles and 
assembles the source files, naming the resulting object files by replacing the .c 
or .s suffixes with the .o suffix, Then, it links the object files with the C run- 
time startoff routine and the standard C library, and leaves the result in file 
file.prg, If only one object file is created during compilation, it is deleted after 
linking; however, if more than one object file is created, or if an object file of 
the same name had been written before the present compilation, the object files 
are not deleted. 


e¢ looks for the compiler and its other tools in directories that the user names. 
The names of these directories together compose ce's environment, and each 
name comprises an environmental variable, An environmental variable is set 
through the micro-shell msh, by using the command seteny, The user must set 
the following environmental variables for ce to work correctly: 


LIBPATH This names the directories that hold the phases of the compiler, 
the libraries, and the C run-time start-up routines, Note that 
you have more than one version of a file, ce will use the first 
one that it finds along the LIBPATH, 


INCDIR This names the “default” directory within which the C 
preprocessor epp.prg will look for files that are called with @ 
#include statement, This default directory is searched along 
with the directory of the source file and the directories specified 
with =I options. 


IMPDIR This names the directory into which temporary files should be 
written, The default if this variable is not set is the directory in 
which the source files are kept, Note that this variable need be 
set only if space is a problem on any of your storage devices, 


‘These environmental variables should be set in your profile file. See the entry 
for msh for more information about profile. 


cc's behavior may be altered by means of command line options. These are 
described below. ce passes all other options through to the linker Id unchanged, 
and correctly interprets to Id the ~e, -o, and -u options, which are described 
below. 

The C compiler itself consists of several phases. The preprocessor epp expands 
adefine and #include directives, among others, in the source program, The 
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parser_ce0 parses the preprocessor output. The code generator ecl generate 
Code for the program, The optimizer ce2 optimizes the generated code and 
writes the object file. If an assembly-language listing is requested, the disa 
sembler ee3 writes it 


(to invoke the editor automatically when errors occur), -f (to include floating- 
point routines), -Iname (to pass the name of a library to the linker), 0 mai 
(rename the executable file), -V (run in verbose mode), and a number of the 
=Vsiring vaviant options 


-A  MicroEMACS option. If an error occurs during compilation, 
automatically invokes the MicroEMACS soreen editor, The error or er 
rors are displayed in one window and the source code file in the other, 
with the cursor set to the line number indicated by the first error m 
sage. Typing <ctrl-X>> moves to the next error, <etrl-X>< moves to the | 
previous error, To recompile, close the edited file with <ctrl-Z>. Com= 
pilation will continue either until the program compiles without error, o 
Until you exit from the editor by typing <etrl-U> followed by <ctrl 
Xp<etrl-C> 


-Bistring] 
Backup option. Use alternate versions of the compiler for ec0, ccl, co2, 
and ec3, If string is supplied, ec prepends it to the names of the phases of 
the compiler to form the pathnames where these are found. Otherwise, ce 
prepends the name of the current directory. If a -t option was previously, 
given, only the parts of the compiler specified by it are affected. Any 
fumber of -B and ~t options may be used, with each ~t option specifying 
the passes affected by the subsequent -B option, For example, th com= 
mand 


0 ~te2 -Bnew hel love 


will compile hello.c using newee? in place of the ordinarily used \[ib\ee2, 
and using newepp in place of the ordinarily used \lib\epp. 


‘Compile option. Suppress linking and the removal of the object files. 


Define namie to the preprocessor, as if set by a #define directive, If value 
is present, it is used to initialize the definition, 

E Expand option, Run the C preprocessor and write its output onto the: 
standard output. 

f Floating point option. Add object files with flcating point output to the 
linker command ling, Because the floating point conversion routines re- 
quire approximately five kilobytes, the standard C library does not in~ 
clude them; the -f option tells the compiler to include them. if a program 
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is compiled without the -f option but attempts to print a floating p 
number during execution by using the e, f, or g format specifications to 
printf, the message 


You mst compile -f 


will be printed and the program will exit. 


-Idirectory 
Include option. Specify the directory the preprocessor should search for 
files given in include directives, using the following criteria: If the 
#inelude statement reads 


Hinelude "i Lesh 


ce searches for file,h first in the source directory, then in the directory 
named in the -Idirectory option, and finally in the system's default direc- 
tories, If the #include statement reads 


Hinclude <file.t> 


ce searches for file.h first in the directory named in the -Idirectory op- 
tion, and then in the system's default directories. Multiple -Idirectory 
options are searched for in their order of appearance. 


-K Keep option. Save the intermediate files generated during the compils- 
tion in the current directory, using file names generated by replacing .c 
with a descriptive suffix. 


-L name 
library option. Pass the name of a library to the linker, ee expands 
~Iname into litname.a and searches LIBPATH. 


-M string 
Machine option, Use an alternate version of ce0, ect, ecla, cclb, ec?, 
cc3, as, lib.a, and rts0.0, named by fixing siring between the directory 
name and the pass and file names. 


-N(p0123sdirt}string 
Name option, Rename a specified pass to string. The letters p0123sdirt 
refer, respectively, to epp, c¢0, cl, ec2, ec3, the assembler, the linker, 
the libraries, the run-time start-up, and the temporary files. For ex~ 
ample, the -VGEM option described below implicitly executes the option 
-Nrertsg.o to change the name of the run-time start-up module, 


=o name 
‘Output option, Rename the executable file from the default file.prg to 


~a(p0123s] . 
quit option. Terminate compilation after running the specified pass. The 
letters p0123s refer, respectively, to cpp, cc, cel, ce2, ce3, and the as- 
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sembler, For example, to terminate compilation after running the parse 
ce0, type -90. 


-Q Quiet option. Suppress all messages. 


Suppress the object-writing and link phases, and invoke the disassemb} 
€c3. This option produces an assembly-language version of a C proges 
for examination, for example if a compiler problem is suspected. Th 
sembly-language output file name replaces the .c suffix with .s. This ig 
equivalent to the -VASM option, 

-U name 


Undefine symbol name. Use this option to undefine symbols that # 


preprocessor defines implicitly, such as the name of the native system of 
machine. 


-V__ Verbose option. ce prints onto the standard output a blow-by-blow 
description of each action it takes. This option is normally used for to 
check the compiler if you suspect something is wrong with it; it can also 
be used on heavily loaded system to reassure the user that compilation i 
in fact proceeding, 


Vstring 


Variant option. Toggle (i.e,, turn on or off) the variant string during th 
compilation, Options marked Strict: generate messages that warn of # 
conditions in question. ce recognizes the following variants: 
-VASM Output _assembly-language code; identical to -S option 
above, Default is off. 


-VCNEST Allow nested comments. Default is off. 

-VCOMM Permit .comm-style data items. Default is on. 

-VELOAT Include floating point printf routines. Same as -f option, 
above. 


‘Use routines designed for GEM environment, This uses run= 


time startup routine ertsg.o and links in the libraries libaes. 
and libvdi.a. Default is off. 


-VGEM 


-VGEMACC Use routines designed fora GEM desk accessory. This uses 

runtime startup routine ertsd.o nd links in the libraries 
aes.a and libvdi.a. Default is off, 

-YGEMAPP Use foutines designed for 2 GEM application. 
synonym for -VGEM, Default is off. 

-VNOOPT Turn off optimization, Default is off. 

-VNOTRAPS 
Turn off wap substitution, By default, all gemdos, bios, 
xbios, and micro_rtx calls are traps. By’setting this option, 


This isa 
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subroutine calls will be generated instead of traps. A trap is 
 single-word instruction, analogous to an interrupt; it is 
faster and takes up less space than an ordinary subroutine 
call. This option allows the user to test routines that have any 
of the aforementioned names. Default is off. 


-VPSTR Put strings into the shared segment, if possible. Used to 
generate ROMable code, Default is off 


-VQUIET Suppress all messages; identical to ~Q option. Defaults off. 


-VSBOOK Strict: note deviations from The C Programming Language, 
Default is off. 


-VSCCON Strict: note constant conditional. Default is off, 


-VSINU Implement struct-in-union rules instead of Berkeley-member 
resolution rules. Default is off, ie., Berkeley rules are the 
default. 


-VSLCON Strict: int constant promoted to long because value is too big 
Default is on. 


-VSMEMB Strict: check use of structure/union members for adherence to 
standard rules of C. Default is on. 


-VSNREG Strict: register declaration reduced to auto. Default is off. 
-YSPVAL Strict: pointer value truncated. Default is off. 

-YSRTYC Strict: risky types in truth contexts, Default is of f. 
-YSTAT Report commands run and statistics; same as ~V option, 
-VSUREG Strict; note unused registers, Default is off. 

-VSUVAR Strict: note unused variables. Default is on. 


Pause between passes and prompt for disk change, Used with the com- 
piler using single-sided disks. 


See Also 
as, ec0, cel, ec2, ce3, commands, cpp, Id 


ce0-—Definition 
ce0 is the Mark Williams C's parser. Tt parses C programs using the method of 
recursive descent, to translate the program into a tree format. 


See Also 
ce, cel, ec2, ec3, cpp 
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eet -Ceonin 


cel—Definition 


ce2—Definition 


cc3 Definition 


Ceonin—gemdos function 1 (osbind.h) 


cl is the Mark Williams C code generator. This phase generates code from 
trees created by the parser, ec, The code generation is table driven, 
entries for each operator and addressing mode. 


See Also 
ce, ec0, ce2, cc3, epp 


ce2 is the optimizer/object generator phase of Mark Williams C. Tt optimi: 
the code generated by cel, and writes the object code. The Mark Will 
Company compiler uses multiple optimization algorithms, One optimizes j 
sequences; it eliminates common code, optimizes span-dependent jumps, 
removes jumps to jumps. The other function scans the generated 
repeatedly to eliminate unnecessary instructions, 
See Also 

ce, c0, ect, ec3, pp 


‘ced is the disassembler phase of Mark Williams C, It writes its output in as: 
sembly language rather than in object code. This phase is optional, and allo. 
the user to examine the code generated by the compiler. To produce an 
sembly-language output of a C program, use the -S option on the ce comma 
ling; for example, 

ce +8 foo.e 
tells ce to produce a file of assembly language instead of an object module. 


See Also 
ec, ec0, ect, cc2, epp 


Read a character from the standard input 
include <osbind.h> 
long Ceonin() 


Ceonin reads a character from the standard input and echoes it to the stand 
output. It returns the character read. 
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Lexicon Cconis 


Example 
This example gets characters from the keyboard and displays them on the 
screen until a <ctrl-Z> is typed. 


#inelude <osbind.h> 


saing) ¢ 
ine e 
hile ce t= OxtA) 
Ceonoutedint (© = Geaningy)); 
> 
See Also 
gemdos, TOS 


Cconis—gemdos function 11 (osbind.h) 
Find if a character is waiting at standard input 
include <osbind,h> 
't Ceonis() 
Cconis checks to see if characters are waiting at from the standard input, Tt 
returns -1 if a character is waiting, and zero if no character is waiting, 
Example 


This example displays a moving asterisk until any non-shift key is typed. 
Ceonis is also demonstrated in the example for Cauxi 


Wine Luee <oabiendshe 


main ¢ 
int x 
int dir 
Ceons(\ 03340339 /* None, cursor disabled */ 
shite (eonis¢) #= 0) ¢ [P Until a key is typed */ 
flair == 09 € Uf Sf Left to right */ 
Ceonws(\010 mp; 
iftere > 78) 
dicts 
2 else € (Uf if right to Left *7 
Cconwsc"\OtO\OYO\O33K"); /* Back up, clear to end #/ 
if cx eo) 
ira; 
> 
5} 
k= ceoningo: /f Eat the character */ 
Ceonas¢"\0830"9; (Tura cursor on. */ 
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‘Ceonos-Ceonrs 


‘Ceonos—gemdos function 16 (osbind.h) 


‘Ceonout—gemdos function 2 (osbind.h) 


See Also 
gemdos, screen control, TOS 


‘Check if console is ready to receive characters 
#include <osbind.h> 
Tong Ceonos() 


Coonos checks to see if the console is ready to receive characters, Tt returns ~ 

if the console is ready, and O if it is not. 

Example 

‘This program exits with a status of 1 if the console cannot be written to; oth 
, it displays a message and exits with a status of 0. 


include <osbind. hy 


ming) € 
FF (Ceonos¢) == 0) € 
exit; 
> 
Ceonws¢iThe console is ready..-\n\r") 
exit(O); 
> 
See Also 


gemdos, screen control, TOS 


Notes 
‘As of this writing, Ceonas always returns -1, and does no checking. 


Write a character onto standard output 
clude <osbind.h> 
yoid Coonout(c) inte; 


Ceonout writes character c onto the standard output. It returns not 


8. 
For information on the screen handling escape sequences used by this routine, 
see the entry for screen control 


Example 
For an example of this function, see the entry for Cauxin, 
See Also 

gomdos, screen control, TOS 


Coonws 


Cconrs—gemdos function 10 (osbind.h) 
Read and edit a string from the standard input 
sinclude <osbind.b> 
void Ceonrs(string) char *strings 


Cconrs reads and edits string, which it receives from the standard input. The 
first byte of string holds the length of the data portion of the buffer; the second 
byte holds the actual number of characters read; and the remainder holds the 
characters read, with a NUL character appended to the end, 


Example 

This example reads an edited string from stdin and writes it and its length to 
stdout. buff{0] is the the size of the data portion of the buffer, and buffll] is the 
length read. 


include <osbind.h> 
rind € 
Unsigned char buf 1303; 


bortior = 128; 
ceonretbul >; 
printf(string 1X3! fs Xd bytes long\nm, abuFF 27, buFFETD); 


3 


See Also 
gemdos, TOS 


Notes 
<ctrl-C> aborts a program if typed in response to a Cconrs, 


Cconws—gemdos function 9 (osbind.h) 
Write a string onto standard output 
#include <osbind.h> 
void Ceonws(string) char *string; 


Ceonws writes string onto the standard output, It stops writing when it reads 
the NUL, Cconws returns nothing. 


Example 

This example writes a NUL-terminated string to stdout. Note the \r used with 
the \n. 

Hinelude <osbind.h> 


paing) € 
Coonms("This fs 2 NuL-terminated string.\r\n"9; 


> 


See Also 
gemdos, screen control, TOS 
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ed-ceil 


ed—Command 


ceoil—General function (libm.a/ceil) 


126 


Notes 
Note that <etrl-S>, <etel-Q>, and <ct 
and abort while Cconws is acting. 


Co act, respectively as XON, XOFE, 


Change directory 
ed directory 


‘The micro-shell msh keeps track of the directory in which the user is currently. 
working, If a command is not specified by a complete path name beginning 
with the name of the storage device on which it is kept, msh prefixes it with the 
name of the current working directory. ed changes the current working dires 
tory to directory, If no directory is specified, the directory named in 
SHOME environmental variable becomes the current working directory. 


For example, consider a disk on drive B:\ that has two directories: foo and bar. 
By definition, the root directory is B:\. and foo and bar each are sub-directories 
of B:\, To change to the sub-directory foo, you would type: 


ed foo 
To move from foo to bar, type the full path name of bar: 
ed bs\bar 


Note that the symbol *.. stands for a directory's parent directory; in. this ex— 
ample, both foo and bar have B:\ as their parent directory. By definition, a 
root directory has no parent. So, to move back from bar to foo, you could type: 


ou from bar to bar's parent directory, B:\; then from the 


See Also 
commands, msh, pwd 


‘Numeric ceiling function 
include <math.h> 
double ceil(=) double 


ceil returns a double-precision floating point number whose value is the 
smallest integer greater than or equal to =. 

Example 

The following example demonstrates how to use ceil: 
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char-character constant 


winetude <math.b> 
dedisplay(value, nase) 


double value; char *enanez 
c 
4 (errno 
perror(nane! 
alse 
printfomciog Xe\n", value, name): 
5} 
Hotine displayx) dodisptayttdouble (x), "ty 
nnaing < 
extern char *aets(9; 
Souale x; 


char stringtés1; 


foresi) ¢ 
printftventer number 
Hf(getsstring) == 0) 
break: 
tof (string; 


display(x: 
display(eei l(a); 
display floor); 
display( fabs 

displaylsqrt(x); 


> 


See Also 
abs, fabs, floor, frexp 


char—Definition 
char is a C data type. It is the smallest addressable unit of data, and it usually 
consists of eight bits (one byte) of storage. By definition, sizeof char equals 
one, with all other data types defined as multiples thereof. All Mark Williams 
compilers sign-extend char when it is cast to a larger data type, 


See Also 
byte, data formats, declarations, unsigned 


character constant—Definition 
A character constant is a constant of the form *X", where ¥ is any printable 
character, and is enclosed between two apostrophes. The value of the constant 
is the machine value of the character it represents, whatever it might happen to 
be on your system. 
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clearerr-CLK_TCK. 


clearerr—STDIO macro 


CLK_TCK—Manifest constant 


Selected non-printable characters can also be represented as character constai 
by using the following escape sequences: 


\o NUL 
\ONN octal number 
\a bell 


\b backspace 
\f formfeed 

\n newline 

\r carriage return 

\t tab character 

\v__ vertical tab 

\ x hexadecimal number 


‘An octal value can also be directly output by preceding the three 
umber with a backslash ‘\’; for example 

04s 
will print the letter “A? om any machine that uses the ASCIT table. 


See Also 
'ASCTT, backspace, carriage return, horizontal tab, newline, vertical tab 
The C Programming Language, page 35, 


Present stream status 
#include <stdio.h> 
clearerr(/p) FILE */p5 


clearert resets the error flag of the argument fp, If an error condition i 
detected by the related macro ferror, clearerr can be called to clear it. 


See Also 
ferror, STDIO 


CLK_TCK is a manifest constant that is set in the header file timesh, Tt 
defined as being equivalent to the rate at which the system clock ticks, On 
Atari ST, the system clock ticks 200 times per second, 


See Also 


time, time. 
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clock-emp 


clock—Time function (libe:a/clock) 

Get number of clock ticks since system boot 
include <time.h> 

clock_tclock() 


clock returns the number of times the clock has ticked since the system was last 
turned on. The number of ticks per second is defined by the manifest constant 
CLK_TCK, which is dectared in the header file time.h, Note that this value 
varies from computer to computer. On the Atari ST, the clock ticks every five 
milliseconds. 


clock returns a value of the type clock_t; this type is defined in time.h as being 
equivalent to an unsigned long. Note that this value will overflow clock_t and 
be reset to zero approximately 148 days after the machine is turned on. 


Example 
For an example of this function, see the entry for Pexee. 


See Also 
CLK_TCK, time, time.h 


close—UNTX system call (libe.a/close) 
Close.a file 
close(fd) int fo 


close closes a file that is identified by the file descriptor fd, which was returned 
by ereat, dup, or open, close frees the associated file descriptor. Because each 
program can have a limited number of open files, programs that process many 
Siles should close files whenever possible. Mark Williams C closes all open files 
automatically when a program exits. 


Example 
For an example of this function, see the entry for opea. 


See Also 
creat, open, STDIO, UNIX routines 


Diagnosties 
close returns -1 if an error occurs, such as its being handed a bad file descrip- 
tor; otherwise, it returns zero, 


emp—Command 
Compare bytes of two files 
emp [-Is] filer file? [skipl skip2] 
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Cnecin Lexi 


emp compares file] and file? character-by-character for equality. If filer 
“', emp reads the standard input. 


Normally, emp notes the first difference and prints the line and character posi 
tion, relative to any skips. If it encounters an end-of-file flag on one file but 
‘not on the other, it prints the message “EOF on filen”, The following are th 
options that can be used with emp: 


-1 Note each differing byte by printing the positions and octal values of the. 
bytes of each file. 


-s Print nothing, but return the exit status. 


If the skip counts are present, emp reads skip! bytes on file! and skip? bytes on 
file2 before it begins to compare the two files. 


See Also 
commands, diff, msh d 


Diagnostics 
‘The exit status is zero for identical files, one for non-identical files, and two. 
for errors, e.g., bad command usage or inaccessible file. 


‘Cnecin—gemdos function 8 (osbind.h) 
Perform modified raw input from standard input 
#include <osbind.h> 
long Cnecin() 

Cnecia reads a character from the standard input and returns it. The character 
is not echoed to the standard output. 
Example 

This example reads characters from the standard input device, changes their 
case, and writes them out to the standard output device until a <ctrl-D> charac~ 
ter is typed. 
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Lexicon commands 


include <osbind.> 
Hinelude <etype. > 


paing) € 
unsianed cher 


whilec(escnecing)) t= 0x04) ¢ 
T#Cisupper(e) (* Togale case of char */ 
€ = tolower(e)? 


else 
= couppercen: 

crawiocer; 

ff€e == 0x00) Jf a RETURNS */ 
CraviocOx0A; (Append a Line feed */ 


5} 


See Also 

gemdos, screen control, TOS 

Notes 

‘This routine has been documented elsewhere as recognizing the special 
meanings of the characters <ctrl-C>, <etrl-S>, and <etrl-Qz; this information, 
however, appears to be incorrect, 


commands—Overview. 
Mark Williams C includes a number of commands. They are listed below, with 
the command given on the left and a description on the right. 


ar the archiver/librarian 

as the assembler 

as68toas convert DRI to Mark Williams assembler 
cat concatenate files 

ec the compiler driver 

ed change directory 

emp compare two files 

cp copy a file 

cpp the C preprocessor 

eshcony run under the Beckemeyer C shell 
cursconf change cursor style and position 
date print/set the system date and time 
ab symbolic debugger 

df measure free space on disk 

aift compare two files 

drtomw convert from DRI to Mark Williams 
echo Fepeat/expand an argument 

egrep find embedded strings 

exit leave msh 
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commands Lexi 
file determine file type 
gem run a GEM-DOS program 
getcol get a color palette entry 
getpal get color palette 
getphys get base of physical sereen memory 
getrez ‘get screen resolution 
help print help files on screen 
hidemouse hide mouse pointer 
redraw screen, moving from high to medium resolution 


mtoh 


show 
showmouse 
size 

sleep 

snap 

sort 

strip 

tail 


get/set the keyboard's repeat rate 
force TOS to reread the floppy disk cache 

the linker 

list directory contents 

redraw screen, moving from low to medium resolution 
programming discipline 

MicroEMACS screen editor 

measure free space in RAM 

create a directory 

the Mark Williams micto-shell 

suspend processing for milliseconds 

redraw screen, moving from medium to high resolution 
redraw screen, moving from medium to low resolution 
rename a file 

print symbol tables 

print an octal dump of a file 

format ASCII files for printing 

print the current directory 

create, save, and load a rebootable RAM disk 

remove a file 

remove a ditectory 

sot attributes of serial (auxiliary) port 

set a shell variable 

set a palette color 

set an environmental variable 

set the color palette 

set the physical base of the screen's memory 

set attributes of parallel port 

set screen resclution 

display saved screen image 

show the mouse pointer 

print size of a file 

suspend processing for 1 seconds 

take a “snapshot” of the current screen image 

sort ASCII files 

strip symbol tables from objects 
print the end of a file 


compound number-con: 


tos run unredirected GEM-DOS program 
touch change a file’s date 

unig list/destroy duplicate lines 

unset discard a shell variable 

unseteny discard an environmental variable 
version print/assign version number 

we count words/lines in ASCII files 


Note that many of the commands are built into msh itself, whereas the others 
are executable programs in their own right. For a list of the commands that are 
built into msh, type the command 


set in bin 


Note that commands not built into msh must be stored in one of the direstories 
named in the environmental variable PATH, so that they can be found 
automatically by msh. Note, too, that commands not built into msh can be run 
independently from the GEM desktop; in most instances, this will require that 
the suffix be changed from .prg to .ttp, so the command in question can receive 
arguments. 


For more information on any of these commands, see its entry within the 
Lexicon, 


See Also 
Lexicon, msh 


compound number—Definition 
‘A compound number is a number that consists of two numbers of different 
types. In the context of C, this applies usually to floating point numbers, which 
are constracted of a sign bit; an exponent; and 2 mantissa, or base upon which 
the exponent operates, 


See Also 
data formats, double, float 


TOS device 
TOS logical device for the consale 


TOS gives names to its logical devices. Mark Williams C uses these names, to 
allow the STDIO library routines to access these devices via TOS. con; is the 
logical device that describes the console. 


Example 
The following example demonstrates how to open the console device. 
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os-cosh Lexie 


Hinelude <atdio.h> 


open; 


See Also 
aux, prnz 


Notes 
con: may be spelled con: or CON:. 


cos—Mathematics function (libm.a/cos) 


Calculate cosine 
double cos(radian) double radian; 


cos calculates the cosine of its argument radian, which must be in 
measure. 

Example 

For an example of this function, see the entry for aces. 

See Also 

mathematics library 


‘cosh—Mathematics function (libm.a/cosh) 
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Calculate hyperbolic cosine 
#include <math-h> 
double cosh(radiax) double radian; 


cosh calculates the hyperbolic cosine of radian, which is in radian measure. 
Example 
‘The following example demonstrates how to use cosh: 


Hinclude <math.t> 
dodisplay(value, nane) 
double value; char *nane: 
€ 


¥f Cerro) perrornsne; 
else printf(zi0e Zen", value, nase); 


cp-epp 


define display(0 dodisplay¢caoubley Gn, %*> 
maint) € 

extern char *getst); 

double x; 

char string lsd: 


forts? 


A 

print f(venter nunber: "); 

if(gets¢string) == 0) 
‘ereak 

x = stof(string); 


displayoo; 
SisplayCeosho); 
displaytsionGo) 
displayCtanht) 

> 

> 

See Also 

mathematics library 


Diagnostics 
When overflow occurs, cosh returns a huge value that has the same sign as the 
actual result, 


ep—Command 
Copy a file 
ep oldfile newfile 
ep oldfilel ... oldfileN directory 
ep copies files. In its first form, ep copies the contents of oldfile to newfile, 
which is created if necessary. If newfile is a directory, ep copies oldfile to a 
file of the same name in directory newfile. 


In its second form, ep copies each file, from oldfilel through oldfileN, into 
directory. 


If a file is copied to itself, the result is undefined, but probably undesirable. 


See Also 
commands, msh, my, wildcards 


epp—Command 
C preprocessor 
cpp loption...) [file] 


cpp is the C preprocessor. It performs the operations described in appendix A 
of The C Programming Language such as file inclusion, conditional code selec- 
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tion, constant definition, and macro definition. The ce command runs ep 
the first step in compiling a C program; and cpp can be run by itself. 

cpp reads each input file, or the standard input if no file is specified, pro 
directives accordingly, and writes its product on the standard output. 
product is a C program that is identical to the concatenated input files wi 
preprocessor directives completed. 


The following summarizes epp’s options: 

-DVARIABLE { 
Define VARIABLE for the preprocessor at compilation time. For ex- 
ample, the command 


ce -DLIMIT=20 Fea. 


tells the preprocessor to define the variable LIMIT to be 20. The com- 
piled program acts as though the directive #define LIMIT 20 were in- 
cluded before its first line. 


Strip all comments and line numbers from the source code. This option is 
used for preprocessing assembly language or other sources, and should not 
be used with the other compiler phases. 


<I directory 
C allows two types of #include directives in a C program, ic., #include 
“file.h" and #include <file.h> The -I option adds directories that the 
preprocessor searches for files named in these directives. By default, cpp 
looks for these files in the directory named by the INCDIR environmental 
variable and the directory of the source file. For information on how to 
set this variable, see the Lexicon’s entries for it and for setenv. 


-0 file 
Write output into file. If this option is missing, pp writes its output onto 
the standard output device. which may be redirected. 


~UVARIABLE 
Undefine VARIABLE, as if an #undef directive were included in the 
source program. This is used to undefine the variables that cpp defines 
by default, i.e,, GEMDOS and M6800. 


In addition to the directives described in The C Programming Language cpp 
processes the #assert directive. The form of this directive is #assert constant- 
expression. cpp evaluates the constant-expression, if its value is false (zero), 
cpp prints a diagnostic message on the console. Assertion failures are nonfatal; 
they do not stop compilation. 


Note that epp. like all other phases of the compiler, can_be run on its own. 
Thus, cpp can be used to modify files that do not contain C programs. For ex- 
ample, assembly sources can be preprocessed with epp to provide file inclusion, 
conditional assembly, and macro expansion. All of epp's directives (e.g. #ifdef) 
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can be used. To assemble a file that contains preprocessor directives, use the 
following commands: 

\Libtepp -€ files -0 file.p 

as -gre file.o file-p 
‘As noted above, the option -E tells cpp to omit the source file line number 
directives that it usually provides for the C compiler. 


See Also 
‘assert, cc, ce0, cel, cc2, cc3, #include, Id 
The C Programming Language, page 86 


Cprnos—gemdos function 17 (osbind-h) 
Check if printer is ready to receive characters 
include <osbind.h> 
Tong Cprnos() 
Cprnos attempts to execute a “handshake” routine to see if the printer is ready 
to receive characters. It returns -I if the printer is ready, and 0 if it is not. 
Example 
The following example demonstrates Cprnos. 


include <osbind.h> 


maint) € 
ifceprnost) (= 99 
Ceonwsc*Printer Ready.\n\r 


else 


Ceonus("Printer not ready.\n\e); 


> 


See Also 
‘gemdos, TOS 


Cprnout—gemdos function 5 (osbind.h) 
Send a character to the printer port 
#include <osbind.h> 
void Cprnout(c) int ¢ 
Cprnout sends the character c to the printer port, and returns nothing. 


Example 
‘This example writes 2 line to the printer. 
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include <osbind.t> 
rain() € 
unsigned char "e=*This is printed on the printer.\r\n"; 
while Ge t= NO) 
Cprnoutcteee); 
> 
See Also 
gemdas, TOS 


(Crawein—gemdos function 7 (osbind.h) 


Read a raw character from standard input 
#include <osbind.h> 
Jong Crawcin() 


Crawein reads a raw character from the standard input, and returns it to the. 
calling program. The character is not echoed to the standard output, and th 
special meanings of the characters <ctrl-C>, <etri-S>. and <ctrl-Q> are ig- 
nored. 


Example 
‘This example reads characters from the standard input device, and writes 
characters out to the standard output device until a <ctrl-Z> is typed. Crawein 
is also demonstrated in the example for Cauxin. 
#inetude <osbind.h> 
mmaing? € 
unsigned char ¢; 
whilecce = Craucingyy 


See Also 
gemdos, TOS 


Crawio—gemdos function 6 (osbind.h) 
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Perform raw 1/O with the standard input 
#include <osbind.h> 
Jong Crawio(c) int c; 


Crawio performs raw 1/O with the standard input. If the argument ¢ equals 
OxFF, then a character is read from the standard input and returned. If c does. 
not equal OxFF, then it is written onto the standard output. 
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Example 
This example reads characters from the standard input device, and writes them 
on the standard output device until a <etrl-Z> is typed. 


#inetude <osbind.t> 
ein) € 
unsigned char ez 


See Also 
gemdos, TOS 


creat—UNIX function (libe-a/ereat) 
Create /truncate a file 
int creat(file, mode) char *file; int mode; 


creat creates a new file or truncates an existing file. It returns a file descriptor 
that identifies file for subsequent system calls. If file already exists, its con- 
tents are erased. creat ignores its mode argument. This argument exists for 
compatibility with implementations of creat under the UNIX system and other 
operating systems. 


Example 
For an example of how to use this routine, see the entry for open. 


See Also 
STDIO, UNIX routines 


Diagnostics 
If the call is successful, creat returns a file descriptor. It returns -1 if it could 
not create the file, typically because of insufficient system resources, or nonex- 
istent path, 


crts0.o—C runtime startup 
C runtime startup 


erts0,0 is the runtime startup routine for C programs compiled into TOS object 
format. 


crts0 provides an efficient, portable environment for C programs. When used 
with the micro-shell msh, it can provide arbitrarily long argument lists, easily 
configured environmental parameters, and redirection of up to six input/output 
channels. 
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The runtime startup module, erts0.0, is the first code executed when yor 
program is run. As its first action, it parses the environment string list pa: 
by TOS into a vector of string pointers. This vector is saved in the the variabl 
external char “environ, for the use of the library routine getenv(), and 

as the parameter char *eavpl], for the information of the function main(). 


remainder of the environment vector is an argument vector that should be 
passed as the parameter char *argr[] to the function main(). 


If the parameter ARGV has a value, such as ARGY=CCAP??, then the value 
should consist of characters from the set [CAPF?]. The characters describe 
origin of the system file handles as Console, Auxiliary port, Printer port, File, 
or unknown. The runtime startup stores the value of ARGV, if it exists, into. 
the external variable char * ioyector for the use of the routines that emulate 
the functions of the COHERENT operating system, 


If no ARGY parameter is found in the environment, then the run time start-up. 

program assumes that the program was executed by a simple GEMDOS Pexec().. 

‘The buffer emdtail is parsed to form the argument vector for main(). ARGVIO] _ 
is supplied by the external variable char _emdnamel], which should be supplied 

by your program, or it will be set to ? by the library. The value of the variable 

_iovector will be set to the default CCAP? PPPRERENI TN: 

See Also 

argy, runtime startup, system 


ertsd.o—C runtime startup 
C runtime startup, GEM environment 


crtsd.o is the runtime startup routine for C programs that designed to be used as 
a GEM desktop accessory. 


ertsd.o can be invoked on the ce command line in one of two ways. First, the 
=VGEMACC option will include it, well as the libraries libaes.a and libvdi.a. 
Second, ertsd.o can be used independently of the libraries by using the name 
option Nrertsd.o. 

See Also 

argy, ce, erts0. 


crtsg.o, runtime startup 


ertsg.o—C runtime startup, 
C runtime startup, GEM environment 
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crtsg.o is the runtime startup routine for C programs that use the GEM VDI 
and AES routines. 


ertsg.o is a simple but fast runtime startup routine. Note the following dif- 
ferences from the default runtime startup crts0.0: 


1. ARGV, ARGC, and ENVP are all set to zero. 


2, geteny is not enabled; this means programs that use ertsg.o will cannot 
read environmental parameters. 


3, stderr will send error messages to the auxiliary port rither than to the 
console. 


crisg.o can be invoked on the ce command line in one of two ways. First, the 
-VGEM option will include it, well as the libraries libaes.a and libvdi.a, Second, 
ertsg.o can be used independently of the libraries by using the name option 
Nrertsg.o, 

See Also 

argy, ce, crts0.0, ertsd.o, runtime startup 


esheomy—Command 
Run a Mark Williams C program under the Beckemeyer C shell 
eshcony filename [argument ...| 


cshconv allows users of the Beckemeyer C shell to call the Mark Williams com- 
piler and utilities, and programs that are compiled with Mark Williams C. 

The user must compile the source file eshtomwe.c into one of two executable 
forms, depending on the version of the C shell being used. Users with environ— 
mental C shells (ie,, those in which the seteny command exists) should use the 
default version by compiling 


ce -0 cehconv cebtome.e 


In this version, the environment is reparsed from scratch because the Mark 
Williams run-time start-up truncates the environmental parameter list when it 
finds a statement of the form ARGV=. This environment is then loaded into 
argv{]. and the number of arguments is loaded into arge. Next, the 1/O vectors 
are set to the corresponding input, output, and error files and, finally, eshcony 
calls for the execution of the specified Mark Williams C program, 


Users with pre-environmental C shells (j.¢., those in which the setenv command 
does not exist) must edit the source file eshtomwe.c to set the default environ- 
mental variables to values that match the ones on their system. In particular, 
the user must alter the environmental strings of the following block of code in 
eshtomwe.e: 
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ctime 


>» 


‘Note that double backslashes are necessary to prevent the C ccmpiler from 
terpreting the backslash as a C escape character. 


msh with the following command line: 
Ce “DOLOCSHELL -e esheony eshtonue.e 


In this version, the environmental pointer points to the user-defined environ 
ment defeny[], the 1/O vectors are set to the corresponding input, output, 
error file handles, and cshconv calls for the execution of the specified M: 
Williams program. 

Caveats 

‘Note that the following restrictions are placed on programs run under eshcony; 


1, You must give a complete file name for the program you wish to run. 


2, You must set the environment strings that Mark Williams C requires to 
run properly, ie., INCDIR, LIBPATH, PATH, SUFF, and TMPDIR. 

3. The environments must be in Mark Williams C format, with the exception 
of PATH, which can use the C shell's list separator. 

4. If you redirect stdin to a file or 2 pipe, the program you call will not fi 
EOF on stdin. 

5. _ If you redirect stdout into a file, all material written to stderr will end 
there as well. 


See Also 
argy, commands 


ctime—Time function (libe.a/etime) 
Convert system time to an ASCII string 
char *etime(simep) time_t *timep; 


ctime converts the system's internal time to a form that can be read by humans. 
It takes a pointer to the internal time type time_t, as defined in the header file 
time.h, and returns a fixed-length string in the form: 


Thu Mar 14 11:12:16 wenn 
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Note that time_t is defined as being equivalent to a long. Mark Williams C 
defines the internal system time as being equivalent to the number of seconds 
that have passed since January 1, 1970 00h00m00s GMT. 


ctime is implemented as a call to localtime followed by a call to asctime. 


Example 
For an example of this function, see the entry for asctime. 


See Also 
time 

Notes 

ctime returns a pointer to a statically allocated data area that is overwritten by 
successive calls, 


etype—Overview 
The ctype macros and functions test a character's type, and can transform some 
types of characters into other types. They are: 


isalnum test if a number 

isalpha test if alphabetic 

isascii test if ASCIT 

isentrl test if a control character 
isdigit test if a numeric digit 
islower test if lower case 

sprint test if printable 

ispunct test if punctuation mark 
isspace test if a tab, space, or return 
isupper test if upper case 

toaseii change to ASCII character 
tolower change to lower case 
_tolower change to lower case 
Toupper change to upper case 
_toupper change to upper case 


These are defined in the header file ctype.h, and each is described further in its 
own Lexicon entry. 


Example 
The following example demonstrates the macros isalnum, isalpha, isascii, 
iscntrl, isdigit, islower, isprint, ispunct, isspace, and toupper. It changes a text 
file to all upper-case characters, and prints some information about the type of 
characters it contains. 


ims C 143 


ctypech L 


Hirclude <ctype.h> 
Finclude <stdio.h> 
mainte 
FILE “fp: 
int filename (200; 
int 
int 
int 
int 
int space = O; 


prinef(wencer nane of text file to examine: 
‘eta(filenane): 
Ff fp = fopent#ilenane,se")) t= MULL) © 
‘while ((ch = fgeteCtp)) t= EOF) € 
ifCisasciigen) € 


ifCisentrt¢eh)) controtes; 
$fCisprint(eh)) printablees; 
Sf Cispunet(eh)) punctuation; 


puteharcistower(ch) ? touppercch) = ch); 


Dalse € 
print#(e fs not ASCII.\n, filename); 
exitttd: 

> 


> 
rintftmis has the following: \n", fi Lensoe 
rintf(wid alphanumeric characters\n", alnun) 
printf(id alphabetic characters\n*, alpha); 
printf(%d control cherseters\n", control; 


printfcomd printable characters\n", printabled; 
eF(d punctuation marks\n", punctuation); 
printfCRd white spece characters\n", space); 
exit; 
D else printf (cannot open *%s".\n", Filename) 


) 


See Also 
ctype.h, Lexicon 


ctype.h—Header file 
Header file for data tests 
#include <ctype.h> 
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ctype.h is a header file that holds the texts of the macros described in the over- 
view entry etype 

See Also 

ctype, header file 


cursconf—Command 
Set the cursor’s configuration 
cursconf task [rate] 


cursconf is a command that uses the xbios function Cursconf to alter the cur~ 
sor's configuration. It can take one or two arguments. task indicates what to 
do, as follows: 


hide the cursor 

show the cursor 

set the cursor to blink 

set the cursor not to blink 
set the cursor to blink at rate 
return the current blink rate 


waunae 


If task is set 10. 4, then you should give eursconf the argument rate, which sets 
the rate at which the cursor blinks. rate should be set to proportions of the 
normal rate parameter, which is one half of the normal cycle time (60 Hz for 
the color mmonitor, 70 Hz for the monochrome monitor, and 50 Hz for 
monitors set in PAL mode). For example, setting rate to 35 will cause the cur- 
sor to blink twice a second on a monochrome monitor. 


See Also 
commands, TOS 


Curscoaf—xbios function 21 (osbind.h) 
Get or set the cursor’s configuration 
#include <osbind-h> 
include <xblos.h> 
Int Curseonf( function, rate) int function, rate; 


Cursconf gets or sets the cursor’s configuration. function is an integer that tells 
‘TOS to do one of the following: 
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Hide the cursor 

Show the cursor 

Set the cursor to blink 

Set the cursor not to blink 
Set the cursor to blink at rate 
Return the current blink rate 


rate, as noted above, sets the rate at which the cursor blinks. It is used to s¢ 
the rate only if function is set to 4; otherwise it is ignored. rate should be set 
proportions of the normal rate parameter, which is one-half the normal cycl 

ime (60 Hz for the color monitor, 70 Hz for the monochrome monitor, and 
Hz for monitors set in PAL mode). For example, setting rate to 35 will cause 
the cursor to blink twice a second on a monochrome monitor. 


Note that Cursconf returns the current cursor blink rate when function is set 
5; otherwise, it returns a meaningless value. 


Example 

‘This example creates a utility for the micro-shell msh that can turn off or tur 
on the cursor’s blink mode. Because this example uses argv, do not compile it 
with the -VGEM option. For an example of using Curstonf in a GEl 
program, see the entry for \auto. 

include <osbind.t> 

define JUNK 50 7* Place-holding value that has no nearing */ 


eincarac, srav) 
int ree; 
char *eravil; 
t 
i (earge-t) = 0) € 
Curscont(S, JUNE); 


else if ((Cargc-1) == 1) BE (strempCargvttl, "blink = 0) € 
cursconf(2, MK); 


exitt0); 
a 
alse ¢ 
printfoUsage: cursor (Lina \o"); 
exit: 
> 
> 
See Also 


sereen control, TOS, xbios 
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gaemon—Definition 

‘A daemon, in the context of C programming, is a process that is designed to 
perform a particular task or control a particular device without requiring the 
intervention of a human operator. Under the COHERENT system, for ex- 
ample, the line printer is controlled by the line printer daemon Ipd. The daemon 
periodically checks when a file has been queued for printing; when it detects 
ane, it starts up the printer and passes the file to it without needing human in- 
tervention, 


See Also 
process 


dats formats—Definition 
Mark Williams Company has written C compilers for a number of different 
computers; these computers have different architectures and define data for- 
mats in different ways. Note that these formats may not be compatible with 
code produced by other processors or other C compilers. 


The following table gives the sizes, in chars, of the data types as they are 
defined by various microprocessors. 


5086 8086 

Type SMALL LARGE 28001 28002 68000 PDPI1 VAX 
char q 1 1 1 1 1 1 
double 8 8 8 8 8 8 8 
float 4 4 4 4 4 4 4 
int 2 2 2 2 2 2 4 
long 4 4 4 4 4 4 4 
pointer 2 4 4 2 4 2 4 
short 2 2 2 2 2 2 2 


Mark Williams C places some alignment restrictions on data. Byte ordering is 
set by the microprocessor; see byte ordering for more information. 
See Also 


byte ordering, C language, data types, declarations, double, flcat, memory 
allocation 


data types—Definition 
The following describes the data types recognized by Mark Williams C. The 
left-hand column below gives compound type specifiers mentioned in The C 
Programming Language, the right-hand column gives additional specifiers 
recognized by Mark Williams C. 
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date—Command 
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short int unsigned short int 
Tong int unsigned short 7 
unsigned int _unsigned long int 
Tong float unsigned long 
unsigned char 


The first pair of additional unsigned terms have the same meaning, as do the 
second pair. The type unsigned char is an addition to the language. If used 
arithmetic expressions, it is automatically cast to unsigned int. 

‘See Also 

C language, char, data formats, double, float, int, long, pointer, short, un- 
signed 


Print/set the date and time 
date [-i] [lyymmdd}ihmmt.ss}] 
date prints the time of day and the current date, including the time zone. Ian 
argument is given, the system's current time and date is change¢, as follows: 

ay year (00-99) 

mm month (01-12) 

dd day (01-31) 


hh hour (00-23) 
mm minute (00-59) 
ss seconds (00-59) 


For example, typing 
date S60512161255 


sets the date to May 12, 1986, and the time to 2:12:33 P.M. Note that at least Ak 
and mm must be specified—the rest are optional. The command 


date +i 
displays the current date and time in the form acceptable to date as input. 


The library time conversion routines used by date look for the environmental 
yariable TIMEZONE, which specifies local time zone and daylight saving tim 
information in the format described in etime. 
See Also 

commands, etime, msh, time, TIMEZONE 
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dayspermonth—Time function (libe.a/dayspermonth) 
Return number of days in a given month 
#include <time.h> 
int dayspermonth(month, year) int month, year; 
dayspermonth returns the number of days in a given month of 2 given 
A.D. month is the number of the month in question, from one to 12. year is 
the year A.D. in which month appears. Note that there is no year 0 
See Also 
isleapyear, time, 


(ime. 


db—Command 
Assembler-level symbolic debugger 
db [-fkor] [mapfile} |datafitel 


db is an assembler-level debugger. It allows you to run object files and execut- 
able programs under trace control, run programs with embedded breakpoints, 
and dump and patch files in a variety of forms. 


What is db? 

db is a symbolic debugger, which means that it works with the symbol tables 
that the compiler builds into the object files it generates. For that reason, it 
will not work with programs that have had their symbol tables stripped out. 
Likewise, because db is designed to work on the level of assembly language, the 
user needs a working knowledge of 68000 assembly language and microproces- 
sor architecture. 


Invoking db 

To invoke db, type its name, plus the options you want (if any) and the name of 
the files with which you will be working. mapfile is an object file that supplies 
a symbol table. datafile is the executable program to be debugged. If possible, 
db accesses datafile with write permission. 


The following options to the db command specify the format of program 
-f Map programas a straight array of bytes. 


-k The kernel option, This allows a user to debug all of the Atari ST's 
memory. The default symbolfile in ossym defines the documented 
locations in low memory. The symbol file is used to provide symbolically 
interpreted output. All of the ST's memory, from address 0 in RAM to 
the end of the ROM, is available for display or patching. Note that this 
option allows the user to perform a post-mortem on programs that crash; 
use the command :r to display the registers and the command :f to display 
the fault identifier in the process dump area. These commands are 
described in detail below. 
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© program is an object file. If mapfile is given, it is another object file that 
Provides the symbol table. 
Read file only, even though you can write into it. This is used to give a 
file additional protection. 
Commands and addresses 
db executes commands that you give it from the standard inpul. A command 
usually consists of an address, which tells db where in the program to execute 
the command; and then the command name and its options, if any. 


An address is represented by an expression, which can be built out of one or 
‘more of the following elements: 


+ The‘, which represents the current address. When an address is entered, 
the current address is set to that location. The current address can be ad- 
vanced by typing <RETURN>. 


The name of a register. db recognizes the register names 30 through a7, 
a0 through a7, pe, and sp. Typing the name of a register displays its con- 
tents. 

* The names of global symbols and symbolic addresses can be used in place 
of the addresses where they occur. This is useful when setting a break~ 
point et the beginning of a subroutine. 


+ An integer constant, which can be used in the same manner as a global 
symbol. The default is decimal; a leading 0 indicates octal and Ox in- 
dicates hexadecimal. 


* The following binary operators can be used: 
+ — addition 
= subtraction 
* multiplication 
/ integer division 
All arithmetic is done in longs. 
‘The following unary operators can be used: 


~ complementation 
negation 
* indirection 
All operators are supported with their normal level of precedence. 
Parentheses ‘()" can be used for binding. 


Display commands 

‘The following commands merely display information about program. The sym~ 
bol ‘.’ represents the address, which defaults to the current display address if 
omitted. count defaults to one. 
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address[ count]?[ format] 
‘Display the format count times, starting at address. The format string 
consists of one or more of the following characters: 


reset display address to *" 


string terminated by *\ 
string terminated by ‘\ 
unsigned 

word 

hexadecimal 

time 


+ increment display address 

= decrement display address 

b byte 

e control and non-chars escaped 
C Tike 'c’ except *\0" not displayed 

d decimal 

if float 

F double 

i machine instruction, disassembled 
1 long 

m output ‘\n? 

0 octal 

P symbolic address 

s 

Ss 

x 

y 


The format characters d, 0, u, and x, which specify a numeric base, can be 
followed by b, I, or w, which specify a datum size, to describe a single datum 
for display. A format item may also be preceded by a count that specifies how 
many times the item is to be applied. Note that format defaults to the 
previously set format for the segment (initially i for instructions). Except 
where otherwise noted, db increments the display address by the size of the 
datum displayed after each format item. 


Execution commands 
In the following commands, address defaults to the address where execution 
stopped, unless otherwise specified; count and expr default to 1. commands is 
an arbitrary string of db commands, terminated by a newline. A newline may 
be included by preceding it with a backslash ‘\’. 
[address ]- 
Print address in current display base. address defaults to '.’. The com~ 
mand = assigns values to locations in the traced process. The size of the 
assigned value is determined from the last display format used. You can 
and set display the registers of the traced process, just like ary other ad- 
dress in the traced process. Thus, 


ot 
aa 
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s the value of register dO as 2 long, and then sets (long) d0 to 
To display the character in the low byte of dO, use: 


oie 
To set the low byte of dO to ASCII <esc>, use 
coe3s085 


(address{ count] J=value{ ,value{ value ]..] 
Patch the contents starting at address to the given value, address defaul 
to'!. Up to ten ralues can be listed. 


2 Print verbose version of last error message. 


[address] + 
Print address symbolically. address defaults to. 


[address ]:b[ commands] 
Set breakpoint at address; save commands to be executed when breaks 
point is encountered. commands defaults to .:a\ni+.2i\nx, 


sbr [commands] 
‘Set breakpoint at return from current routine. The defaults are the sa 
as for :b, above. 


[address] © 
Continue execution from address. 


[address] :arlts| 
Delete breakpoint at address. If optional r or s is specified, delete ret 
or single-step breakpoint. address defaults to 


[address}:e[ commandline] ; 
Begin traced execution of the object file at address (default, entry poiat) 
“The commandline is parsed and passed to the traced process. argy[0] mus 
be typed directly after: if supplied. For example, :e3 foo bar baz 
argy{0| to 3, argv[l] to foo, argvi2] to bar, and argy[3] to baz. Quotati 
marks, apostrophes, and redirection are parsed as by msh, but spi 
characters “?*[/ and shell punctuation ‘()()f* are not. 


:f Print type of fault which stopped the traced process. 


[expr }{ filename] 
‘The log option. If expr is non-zero, open filename as a log file; if expr is 
zero, close the currently open log file. db echoes all its responses into 
open log file. 

Lexpr]:a 
‘Set default numeric display base to expr: 8, 10, and 16 indicate, respec 
tively, octal, decimal, and hexadecimal. 
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2 Display breakpoints. 

fexpr}:a : 
Tf expr is nonzero, quit the current level of command input (see :x). expr 
defaults to 1. End of file is equivalent to :q. 


xt Display registers. 
{address}, count }:slel{ commands] 


Single-step execution starting at address, for count steps, executing com- 
mands at each step. commands defaults to .?1. 


After a single-step command, <RETURN> is equivalent to .,L:s{e]. If the 
optional c is present, db turns off single-stepping at a subroutine call and 
turns it back on upon return, 

[depth] t 
Print a call traceback to depth levels. If depth is 0 (default), unwind the 
whole stack. 


[expr] 2 
If expr is nonzero, read and execute commands from the standard input 
up to end of file or :a. expr defaults to 1. 


Example of the commands 

‘The following example shows how each db command can be used to examine an 
executable file. It uses the following C program, called count.e, which counts 
the number of ASCH characters in a file: 


include <etype.h> 
#inelude <atdio.h> 


mainfarae, arav? 
int are 
char "argv 
€ 


FILE *for 
int result, chy 


if (Cf = fopentargvett, #689) t= MULL) © 

eile ((eh = faetectpy) f= FOF) € 
TeCisescii¢eh)) results; 
else Fataltargvlt], "Mot ASCII"; 


2 
prinefos: d characters\n", argytt, result); 

> 

else fatalcargvitl, "Cannot open"); 
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fatalcfilenane, message) 
char *filensne, *message: 
< 

printf(vte: s\n", filename, message); 


> 


For purposes of this example, count.prg will be used to count the characters in 
text file called tester. Its contents are as follows: 


Sonnet 30 


Unen to the sessions of sweet silent thousht 
1 sumon up renesbrance of things past, 
1 sigh the lack of any 9 thing T sousht, 
And with the otc woes new weil ay deer €i 
Then can I droun an eye, unused to flou, 
For precious Friends hid in death's dateless night, 
And weep afresh Love's long since canceled woe, 

And moan the expense of many a vanished sight: 
‘Then can f grieve at grievances foregone, 

And heavily from woe fo woe tell ofer 

‘The sad scsount of fore-benoaned sean, 

Which 1 new pay as if not paid before. 

Sut if the while 1 think on thee, dear friend, 

ALL losses are restored, and sorrows end. 


To begin, compile count.c by typing the following command: 
ee -V countie 

When the program has been compiled, invoke db with the following command: 
ob count.pes 


Addressing commands 

As noted above, db offers several different ways to set the address, or the 
tion within the program that you are examining. One way is by entering a 
able name. Type printf. db replies: 


me's waste: 


prince Link a6, $030 


Another way to set the address is by entering an absolute address. Type 0600 
db replies: 


+ 


‘The symbol"? (dot) echoes the current address. Type a dot; db will reply: 


invt7o se pet 


sox ist printf_at 
which is, as expected, identical to the previous reply. 


‘The equal sign ‘=" displays the absolute address of any yariable that precedes 
To see how this works, type printf=. db replies: 


db 


nies 


which is the address of printf. 


Instructions can be shown, beginning at a named address. The format must be 
introduced with a question mark ‘2. For example, .,2i shows the current line in 
the instruction space, a5 indicated by the format string "2i". When this com- 
mand is typed, db replies: 


mains0x70 jer printf 


Now, show the next five instructions from the current point by typing .,5?i. db 
replies: 


main 30x70 ise 
main $0x76 Laat 
main s0c7k bre 
meins0x7C —move.t 
main +0x82 moves. 


Once a format is set, it remains the default until the format is reset with 
another format string. For example, the command printf,20 prints 20 instruc~ 
tions, beginning with printf; the format 2i remains in effect. Type this com- 
mand. db replies: 


printf Link 36, $030 
prinet Oss peat Ox8(06) 
print 0x8 move. stdout_, -(a7) 
prinefsOxe sr sprint f_s@x3c.t 
printf oOxt  sddg.w  $0x8, a7 
printf 0x16 unk 
printf +0xt8 rte 

ferintt_ Link 26, SOx 
fprintf sax pes.tOxECas) 
fprintfeOx8 ove.t  OxBC36), 


fprintfstxc Isr sprintf s0x3¢.t 
fprintfs0x12 adda 30:8, a7 
fprintfs0Kte unk 6 

Aprintf 0x16 rts 

sprintf Link 96, SOXFFES 


spcintf 0x4 pea. OxFFE6(96) 
sprintf +0x8 move. $0x8000, -¢27) 
sprintf +0xc  move-l0x8(06), -Ca7) 
sprintf-Ox10 Jer _stropen.t 
sprintf 0x16 Leal Beata), a7 


Typing ,20 prints the next 20 instructions, beginning from where the previous 
command left off. When you type this, db replies: 
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sprintf s0xtA paa.tOx0(=6) 
sprintf s0x1& peal OXFFESCa6) 
sprintf +022 jsr sprintf_0x3c. 
sprintf +028 adiq.u SB, a7 
‘sprintfeOxza pee. OxFFE6Ca6) 


sprintfeOze clraw -(07) 
sprintf +030 jr fpute_-t 
Sprint eOGS scdq.u  Sx6, a7 
sprintfeO38 unk as 
sprintfeGx3q rts 

sprintfleOxS¢ Link a8, SOXFFOS 


sprintflsOxs0 oven. 7/6/35, (a7) 
sprintf s0xts move. OxC(56), OxFFFECS6) 
sprintflOxtA moves. GRFFFC(=S), 30 
sprintf +0xtE nove. (209, 

sprintf +0x50 moves. , 96 
sprintfi+0xS2 edlg.i$0x4, OxFFFC(s6) 
‘spcint#s0s56 nove.b (ski, 

sprintf 40x58 ext.w dl 

Sprintfs0x5k move.w fl, a7 


Finally, the command :a displays an address symbolically. The default is 


current address. Type this command: db replies: 
‘sprintf s0K5A 


which is the same address as that of the last instruction in the previous example; 


in other words, the address advanced as the command was processed. 


To reset and display the address at the point where the instruction fatal is, type 


fatala, db replies: 
fatal 
Execution commands 


db allows you to execute portions of your program; this is done by setting 
breakpoints, or points where execution stops. Breakpoints are set with the com= 


mand :b. Set breakpoints at mai 


‘The command :p displays the current breakpoints: 


00000110 «main > f+.78\n=x\n 
o00a1C6 (printt_) 
sooogtAs (fatal_) i 


2i\nea\n 


. printf, and fatal as follows: 


Now, begin execution with the command :e. As noted above, ¢ can take ar 


gumeni 


the arguments correspond to the elements in the array argy; in this ex- 


ample, use the following command to pass as an argument the name of the text 


file tester, whose text is given above: 
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se tester 
db replies: 


ein. tink 6, SOxFFFB, 


‘The program has executed up to the first breakpoint, set on main, The com- 
mand mt performs a call traceback on the stack to n levels; the default is zero, 
which means to unwind the whole stack. Type: 


4b repli 


OXOSSE1O main (OxO002, OXO00S, OXS6TA, OXCOS, OxS5F6) 


Note that the address of main_ has changed because the program is now loaded 
into memory, 


‘The command :¢ continues execution of the program to the next breakpoint. 
‘When you type it, db will reply: 


printt_ Vink 95, $030 
Perform another stack traceback by typing :t. db replies: 


OXO3SDFS print (OxO00S, Ox5208, Ox0008, Ox2061, 0x0272) 
OxOSSETO main (Gx0002, GaD003, OAS6IA, 120008, O355F6) 


Type :c to continue execution to the next breakpoint. db replies: 


tester: 626 characters 

Child process terminated (0) 
The first line shows the output of of the program; in this case, a message that 
the file tester has 626 characters. The message about the child process indicates 
that the program has finished execution and exited: the number in parentheses 
is the value that exit returned to the calling program (in this case, db). 


Now, type :p to print a list of the breakpoints. db makes no reply because no 
breakpoints remain set; all have been erased as the program executed. 


Finally, quit the debugging session by typing :a. 


Example of debugging 
This example shows how to use db to track down a simple bug. Tt uses the 
following program, called bug.c: 

include <stdio.t> 


main) € 
putputcWuLL, stdout); 


send runber to stdout */ 
> 
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cutput¢nusber, 2) 
int runber; 

FILE "fp; 

« 


fpeintttfp, "The muber 1s %4.\n", number); 
> 


This program passes a number to the routine output, which writes it into 
named file or device. The program illustrates « common error in C program: 
ming. 


To begin, compile bug.e by using the following command: 

ce -V bus. 
‘You should see no error messages during compilation. When compilation 
finished, try running the program. Instead of writing its message on the 
dard output device, the program should generate a bus error (as indicated 
the appearance of two “bombs” on the screen), 
Now, invoke db with the following command: 

ob bug prg 
One way to approach this problem is to set 2 breakpoint on main and 
through the program. The following sets the breakpoint: 


meine 


The :e commands performs traced execution at the program's entry point. 
When you type ze, db replies as follows: 


sain Vink a8, $00 


The :s commands performs single-step execution. The following commant 
follows the program through five steps: 


Sc 


db replies as follows: 


mains0x6 moves S.stdout_, -(27) 
mainsOxa clr. =D 

meinsOxc jst cutput_t 
outpat_ Hine 36, $050 


output xk mave.w OxB96), -(67) 
‘The command :t allows you to perform a stack traceback. db replies as follows’ 


GxO343F6 output +0x4(0%0000, 10000, Ox0003, Ox3ACE) 
GxGSLAO6 main +GxtZCOx0001, Ox0603, ‘OxICT4, ox0003, 380) 

The number in parentheses indicate what is being passed on the stack to 

routine. Each four-digit number represents a machine word (two bytes). 

first line indicates the source of the trouble: the routine output is being 1 
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four words, when it is defined as receiving three: an int and a pointer. The 
problem, of course, is that main passed output two pointers, NULL and stdout; 
on the 68000, unlike on some other processors, NULL and zero are not identi- 
cal. (For more information on this topic, see the Lexicon entries for pointer, 
NULL, and dats formats.) 


Another, simpler approach to this problem is to enter db and then immediately 
set a breakpoint with zb, perform a traced execution with ze followed by a stack 
traceback with the xt command. db replies as follows: 

OKOBLSSC fpute +O<52C0x0054, 00000, 00003) 

ex03430¢ sprint #_Ox76¢Ox0060, Ox0003, Ox0003, Ox4340) 

SxOSKSEG fprint#_+0x12(0x0000, 070005, 0x0005, OXSAGA, 0x0000) 

OxDBESFE output “Ox18(Ox0000, 010000, x0003, ‘xSACS) 

OKOBL406 ain s0x12¢Ox0001, 650003, Gr3CT6, Gx0003, Ox38r0) 
Again, the display shows how output was passed an improper argument, which 
‘made it pass an improper argument to fprintf. 
See Also 
commands, od 


Dereate—gemdos function 57 (osbind.h) 
Create a directory 
‘#include <osbind.h> 
Tong Dereate(patii) char *path; 
Dereate creates a directory; it returns zero if the directory was created success 
fully, one if it was not. path points to the subdirectory's path name, which 


should be a NUL-terminated string. Dereate returns a negative value when an 
error occurs. 


Example 
‘The following example uses Dereate to create a directory. 


include <osbind.t> 


aintarge, argv) int arge; cher “argv; ¢ 
Int status; 


if (arse <2) ¢ 
‘Cconus(*Usage: Dereate pathname\r\n"); 
Preract); 
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if (status 
‘errno = ~status; 
perroc(™ereate failure"); 
Prerm(1z 


> 


See Also 
gemdas, TOS 


Delete a directory 
#include <osbind.h> 
long Ddelete(parh) char “path: 
Daelete deletes a directory; it returns zero if the deletion was successful, non- 
zero if the deletion failed.’ path points to the subdirectory’s path name, whick 
‘must be a NUL-terminated string. 

Example 

The following example deletes a directory 

include <etdio.t 
include <osbied. b> 
‘define EACTESS (-36) 


‘extern int errno; 


meintargc, arav) 
int status; 
if carge <2) € 
‘CconvstUsage: Ddetete pathnane\r\n"); 
Prenat); 


Wt arge; cher **ergv; 


declarations 


if (Cetatus = Ddeletecaravet9y? I= 0) € 
Tf (status == EACCESS) C 
‘print f(etderr, "\wirectory %s contains files\n", 
argv); 
p else ¢ 
errno = ~stotus; 
perrorpdetete failure"); 
) 
Preermct); 
> 
priner(sDirectory 6 deleted.\n", aravitt); 
PrermoQ: 
> 
See Also 
gemdos, TOS 


declarations—Overview 
‘Mark Williams C recognizes the following as legal declarations for data types: 


char 
double 

enum 

float 

int 

long 

Tong float 

Jong int 

short 

short int 

struct 

union 

unsigned char 
unsigned int 
unsigned long 
unsigned long int 
unsigned short 
unsigned short int 
void 


‘The following pairs of terms are synonymous; the more commonly used term is 
given on the right: 


fong float 

ong int 

short int 
unsigned long int 
unsigned short int 
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Jong 

short 
unsigned long 
unsigned short 
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#define-desk accessory 


‘#define—Definition 


See Also 
C language, data formats, data types, Lexicon 


‘#define tells the C preprocessor cpp to define a yariable as 2 manifest constant 
For example, the instruction 


Hietine maxanes 9 


tells cpp to replace every instance of the string MAXARGS with the numeral 9 
throughout the program. (Note that aumerals are manifest constants by defini- 
tion.) 


#define instructions are very useful because their judicious use allows a_ 
programmer to write code that more easily understood, maintained, and en= 
hanced. With them, 3 programmer can modify a major parameter throughout 
his program just by changing a single line of code. They also allow a program 
mer to use a variable name that suggests the function of the parameter 
represents; for example, the name MAXARGS within 2 progrm obvious 
refers to the maximum number of arguments, whereas the numeral 9 cat 
refer to nearly anything. 


See Also 
cpp, manifest constant 
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‘A desk accessory is 2 program that is loaded by TOS into the GEM desktop 
when it is booted. The desktop gives each accessory its own icon, Keeps it resi- 
dent in memory, and gives you direct access to it. When you build a menu, 
routine menu 

builds the list displayed under the desk en 


To compile a desk accessory with Mark Williams C, use the optio 
-VGEMACC. This will automatically link in the special run-time start-1 
routine ertsd.o, and otherwise perform all that is needed to create a desk acc 
sory. Note that all desk accessories must have the suffix .acc. Therefore, 
compile the program foo.c into a desk accessory, use the following form of 
ec command: 


‘ce -VOEMACE -2 foo.ace Foo.e 


To install a desk accessory, move the compiled program into your system's r00t 
directory. If you have a hard disk, it should be in directory e:\; otherwise, 
should be in the root directory of the disk with which you boot TOS. Do 
place it into the directory \auto; this will cause all manner of unpleasant thi 

to happen. The program will be loaded into the desktop automatically wheal 
you reboot your system, 
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Because of their specialized nature, desk accessories restrict the number and 
variety of programming tools you can use with them. Note the following: 

+ Do not use any stdio routines 

* Do not use the malloc routines found in libe-a 

* Do not use exit, Pterm, Pterm0, or Ptermres 

* Do not return from main 


Also, you should keep the following in mind as you write your accessor; 


If you use rsc_load, remember to use rse_unload before you give up 
control, if possible. 

* Do not use evnt_timer calis: use evmt_multi instead. 

Example 

The following example is the digital clock desk accessory. It is a public domain 


program written by Jan Gray in 1986. It displays a digital clock on the GEM 
screen. 


#inelude <gendets.> 
#inelude <osbind.F> 


[* Macros to extract tines from TOS tine formst */ 
define MINSCE) (Ce >> 5) B OX34) 

Hefine WeSC) ce >> 11) 
define DIGITESD (oD + 


3 


(* Sone manifest constants */ 
“HdeFine No_uinoow -1 [1 00 window opened */ 

‘define NO_POSITION -1 77 window has no position yet */ 
oetine TERPLATE "hmm AM" 

idetine TEMPLE & 


(A window descriptor, used in this example */ 
typedef struct window £ 


int ie ‘/* COM window 1D from Wind erestet) */ 
int x7 7* X origin on the screen for the window */ 
int yb 7* ¥ origin on the screen far the window #/ 
int 7 width of the window */ 
int hi 77 height of the window */ 

9 Window 


f 
+ Main progran: Initialize the desk accessory and call the 
= routine that maintains the clock. 


” 

meine) ¢ 
int mento; [7 there this 1s on the desk mend */ 
‘extern int @l_apid; 7* The spplicetion ID for this DA */ 
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appt_inito; 
enulD = nena ragistersl_apié, " Digital clock"); 
[7 Register a8 2 desk accessory */ 
77 call event loop routine */ 
2 Never returns! */ 


events¢nenutD)? 


> 


7 Loop processing events; wake up every 30 seconds to update tine. */ 
feventscnenutD? 
int menuiD; 


JF Where this accessory 


fin the desk. 


[7 Place to keep track of the window #7) 
[7 Mich event fem evnt_multi */ q 
( Message buffer */ 

(7 Duemy return buffer */ 

7 

7 Ko windos yet */ 

7 No position for non-existent window */ 


for Gi) € JF Until reboot */ 
‘event = ent eulti@wu_MESAG | MU TINER,/* Wait for either */ 
2, 0, 0, 77 a message or 8 */ 
0, 0, 0, 0, 0, 7 tiger event */ 


1. 9, 0, 0, 0, 
sgbuf, 30000, 0, /* 30 seconds */ 
fret, dret, Bret, dret, Bret, bret); 
(/* Event has been received, now what fs it? */ 
Ff (event £ MU NESAG) switeh CosgbuffO1) ¢ 
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case WH MOVED: 
ind setCwind. ic, WF_CURRKYWH, megbuf{41, mesbut 51, 


case WH TOPPED: 
FF cesabuf ) == wind.1a) 
Wind setcwind.id, WE_TOP, 0, 0, 0, 09; 


(evant & MLTINER a8 wind.id f= No_wINOOW) 


updatet Eine 
> 
> 
p 
* update the title on the clock window to reflect current GENDOS 
# eine. 
* 
updatetwp) 
Window *4p; J The clock window descriptor */ 
‘ 
static char timet] = TEMPLATE; /* Tine string buffer */ 
unsigned t = Tgettinet); 7 the current Dos tine */ 
Unsigned hre = ARSCED: 7 extract hours */ 
unsigned hrst2 = (hrs X 12 == 0) 712 2 hrs X 12; 
unsigned mins = MINSCE); /* extract minutes */ 
‘e 


* Create tine string for window title... 

* Do things the hard way: sprintf) would spend too mich memory. 

" 
tine t01 
inet] 
inet 
‘ime (6 
time(6l = hrs < 12) 7 AY 
wind settum->id, UF_AAME, &) 


8, 07:7" set 


indow title to tine */ 
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oa 
* create and open # window just big enough to hold the tine on its title bar 
+ and the CLOSER box. 


+ 
operiindowesp 
Window *up; 7? Windou descriptor */ 
r 
(PP work aren width */ 
77 work area height */ 
7 Dumy return buffer */ 
[7 18 there 
Wo_POSITION) € /* If there Is no post! 
» 


' Position the clack in the center of the screen. This is 2 hack to 
* determine the size and position of the window. 
” 
graf _handletinp->u, Bret, ret, kup->h); 
spon *= TEP LEN + 
Wind setcO, UF MOROCTN, Bup->s, Eap>y, 
‘aor, Burke); 


> 


7* Create @ window with nane, closer and moveable *"/ 
wp->idl = wind create(NAME|CLOSER|MOVER, 
Sp>m, MEO, MEM, MONE 
1 MBP, MODY, MBO, WRN: 


> 
> 
([ Renove the time Kindo from the sereen */ 
closeuindoxCwp) 
Window sp ([* Windos descriptor *7 
« 
if Gape>id t= Wo_wINOO) € I only if there is 2 window */ 
wind closetup->idd: 7 close that window */ 
Wind _delete(up->ia 7 delete that window */ 
wp->id = No_MINDOw: (7 renesber it's gone */ 
> 
> 
See Also 
ertsd.o, TOS, 


“Measure free space on disk 
df [-al device 


Dire 


‘df measures the amount of free space left on a floppy disk, on a logical device 
on a hard disk, or on a RAM disk. device is the name of the device you wish to 
check; for example, to check the amount of space left on the disk in drive A:, 
type: 

dear 
‘The default device is the one you are logged into. 
‘The option -a prints the amount of space left on all devices. 


See Also 
commands, mf, msh 


‘Dfree—gemdos function 54 (osbind.h) 
Get the location of free space on a drive 
#include <osbind.h> 
void Dfree(fs, drive) long fs{4}; int drive; 


Dfree retrieves information about free space on a disk drive, and writes it into 
the arguments fs and drive, which it keeps. fs points to an array of four un- 
signed longs that hold, respectively, the amount of free space on a drive, the 
number of clusters on the drive, the sector size in bytes, and the cluster size in 
sectors. drive is the number of the disk drive itself, with zero indicating the 
default drive, one indicating drive A, etc. 


Example 
This example displays disk statistics for the default drive, 


Hinelude <osbind. b> 


struct diek info ¢ 
unsigned long di_free; /* free allocation units */ 
42 bow many AUS on disk =/ 
7 sector size */ 
7 sectors per Al */ 
% 


raing) 


struct disk info disk; 
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‘Dgetiiry—gemdos function 25 (esbind.h) 


Dgetpath—gemdos function 71 (osbind.h) 


od = Dgetdeve9; 
Dfrecckdisk, doh 
diskedi t 
disk-d?_spautdisk-di, 
fs * disk.di_ssize; 
ts * diskici seize, 
printf(*Disk ez has %d bytes free in Ud sectorsint, 
aAt, fb, F835 
printf(#fron total of Ad bytes In 34 stctors (cluster size %2)\n", 
th, ts, disk.di_spautdisk.di_ssize); 


peu; 
anys 


> 


See Also 
gemdos, TOS 


Find which disk drive is the current drive ees 


+#include <osbind.h> 
int Dgetdrv() 


‘Dgetdry returns an integer that indicates the current drive: 0 corre: 
drive A, and so on through 15 corresponding to drive P. 


Example 
‘This example prints the default drive. 


include <osbind.h> 


is the current default drive.\n", 
{ehary ogetdrve) + +44): 


See Also 
Dsetdrv, gemdos, TOS 


Get the current directory name 

#include <osbind.h> 

long Dgetpath(4u/fer, drive) char *buffer; int drive; 
Dgetpath gets the name of the current directory. Suffer points to the 
where the buffer name is to be stored. drive holds a number that indicates th 
disk drive to be examined, as follows: 0, the default drive: 1, drive A; etc. 
Example 

This example prints the current path name and device string. 


ditt 


include <osbind.t> 


raing) ¢ 
int dtvz 
char pathbuf (66); (7 Path buffer #7 
char buf; 


hut 


7 cet drive +7 
pay 

7 Rest of path */ 
printft*current path is %s\n", pathbut ); /* Display it */ 


Fy 


See Also 
Dsetpath, gemdos, TOS 


dift—Command 
Summarize differences between two files 
diff |-b] [-c symbol] file! file2 


diff compares file with file2, and summarizes the changes needed to turn file! 
into file2. 


Two options involve input file specification. First, the standard input may be 
specified in place of a file by entering a hyphen ‘-" in place of file! or file2. 
Second, if filel is a directory, diff looks within that directory for a file that 
hhas the same name as file2, then compares file? with the file of the same name 
in directory filel. 

‘The default output script has lines in the following format: 

az|e3e 

The numbers 1,2 refer to line ranges in filel, and 3.4 to ranges in file2. The 
range is abbreviated to a single number if the first number is the same as the 
second, The letter ‘c” indicates that lines 1,2 of file! should be changed to lines 
3,4 of file2. diff then prints the text from each of the two files. Text a5- 
sociated with file! is preceded by “<*, whereas text associated with file2 is 
preceded by ‘>. 


The following summarizes diff’s options. 


-b Ignore trailing blanks and treat more than one blank in an input line as a 
single blank. Spaces and tabs are considered to be blanks for this com- 
parison, 

~ symbol 
Produce output suitable for the C preprocessor cpp; the output contains 
#ifdef, #ifndef, else, and #endif lines, symbol is the string used to 
build the #ifdef statements. If you define symbol to the C preprocessor 
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difftime-Dosound 


difftime—Time function (libe.a/difftime) 


direetory—Definition 


Dosound—xbios function 32 (osbind.h) 


170 


cpp, it will produce file? as its output; otherwise, it will produce 
Note that this option does not work for files that already contain #ifd 
#ifndef, #else, and #endif statements. 

See Also 

commands, egrep 


Diagnostics 
diff’s exit status is 0 when the files are identical, 1 when they are different, 
2 if a problem was encountered (e.g., could not open a file). 


Return difference between two times 
include <time-h> 
double difftime(simel. time2) time_t timel, time2; 


difftime calculates the difference, in seconds, between time! and time2. 
Both arguments are of type time_t, which is the current system time, 


which is defined in the header file time.h. Note that the function time retu: 
the current time in this format. 


Mark Williams C defines the current system time as being the number 
seconds since January 1, 1970, 0h00m00s GMT. 


See Also 
time, time-h 


A directory is a function that maps names to files; in other words, it associ 
the names of a file with their locations on the mass storage device. Under som 
operating systems, directories are also files, and can be handled like a file. 


Directories allow files to be organized on 2 mass storage device in a ration 
manner, by function or owner. Note that the documentation for TOS uses 
term “folder” as a synonym for “directory”. 


Start up the sound daemon 
#include <osbind.h> 

#include <xbios.h> 

void Dosound(Suffer) char *buffer; 


Dosound 


Dosound starts up 2 daemon to control the sound generator. fuffer points to 
buffer that holds the commands and arguments to be passed to the daemon, 


Each command consists of an eight-bit hexadecimal number followed by one or 
more characters; the commands are as follows: 


0x00-0x0F 
Each of these commands is followed by a one-character argument; each 
writes its argument into the appropriate register in the GI sound gener- 
ator, with 0x00 corresponding to register 0, Ox0! to register I, and so-on, 
For a fuller explanation of what each register governs in the sound 
register, see the entry for Giaccess. 


0x80 This takes a one-character argument and writes it into the temporary 
register. 


0x81 This command takes three one-character arguments. It takes the character 
that had been loaded into a temporary register with the 0x80 command, 
loads it into a sound generator register, and controls its execution, The 
first argument is the number of the register into which the previously 
stored character is to be loaded. The second argument is a two's- 
complement number that is added to the contents of the temporary 
register. The third argument is an end-point value. The instruction that 
was loaded is executed continually, once each update, and the contents of 
the temporary register are incremented; this process ends when the value 
stored in the temporary register equals that of the end-point value. 


0x82-0xFF 
Each of these commands takes a one-byte argument. If the argument is 
zero, sound processing is halted. If the argument is greater than zero, it is 
taken to indicate the number of timer ticks (each tick being 20 
milliseconds long) that must pass until the next sound process is per- 
formed. In effect, these commands can set how long a tone is sustained. 


Example 
This example generates an interesting series of sounds. Type s key after the 
bell sounds. 


Winelude <osbind.h> 


char nofsen=¢ 
‘OnFF,, 0350, 77 delay a shite... 7 
9x00, 7 Load reg 0 (channel A freq, fine) */ 
7 Lead reg 1 (Channel A freq, coerse) */ 


9x02), 7 Load reg 2 (Carvel § freq, fine) */ 
805, /* Load reg 3 (Channel & freq, coarse) */ 
x04, 7* Load reg & (Channel C freq, fine) */ 
x05, 77 Load reg 5 (Channel C freq, coarse) */ 
x05, 7 Losd reg & Giofse period) =/ 


m1 


Dosound 


x07, OxF8, 19 Load rea 7 (Wotce enable) */ 

x08, Ox10, 7 Lead reg 8 (Channel A volume) */ 

Ox0F, Oxt0, 77 Load reg 9 (Channel 8 volume) */ 

OxOK; oxt0, 7? toad reg A (Channel € volume) */ 

Ox0a, 0100, (7 Lead reg 8 (Env period fine tune £) */ 
‘x0, 0350, [7 oad reg © (Env period coarse tune E) */ 
‘x00, 0x09, 77 Load reg D (Env shape/cycle) */ 

OxFF, 0330, [7 delay */ 

000, 0x00, 7 Load reg 0 (Channel A freq, fine) */ 
oxot, ox0t, 7 Load reg 1 (Channel A freq, coarse) */ 
O07, Ox3E, 7 Load reg 7 (Voice enable */ 

x08, 0308, (F Load reg 8 (Channel A vol) */ 

oxo9, 0300, J Load reg 9 (Channel 8 vol) */ 

xO, x00, 7 Load reg A (Channel C vol) */ 


fined */ 
” coarse) */ 
x02, 9x00, 11 Load reg 2 (Channel 8 freq, tine) */ 
x03, 0x00, ( Losd reg 3 (Channel & freq, coarse) #/ 
0x06, 0x00, 77 toad reg 4 (Channel € freq, fine) */ 
0x05, 0x00, JF Lead reg 5 (Channel € freq coarse) */ I 
0x06, 0x00, 77 oad reg & (Noise period) "7 i 
x07, OxFE, 7f Load reg 7 (oice enable) #7 
9x08, Oxt0, [7 toad reg B (Channel A vol) */ 
0x09, 0x00, 77 Lead reg 9 (Channel B vol) */ ) 
Ox0A, 0x00, 7 Load reg A (Channel € val) */ 
x08, 0x00, 7 Load reg 8 (Env period fine tune £) 47 
oxoc, Oxt0, 7 Load rea C (Env perfod coarse tune £) */ 
0x00, 0309, 7 Load reg D (Env shape/eyele) "7 
OxFF, x00 7 Terminate delay tiner */ 
% 
waing) € 
Dosounde noise 2; (Jf Make sone noise... */ 
while ( teenie) == 0) —/* Loop until user types a key */ 
Cconms(*Listen... "9; 
eeoning) 77 Get the key. “7 
Dascurd noise}; 77 Wake some nofse agzin */ 
> 
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Lexicon double-drtomw 


See Also 
daemon, Giaccess, TOS, xbios 


double—Definition 

‘A double is the data type that encodes a double-precision floating-point num- 
ber, On most machines, sizeof(double) is defined as four machine words, or 
eight chars. Programmers who wish to write portable code should no! use 
routines that depend on a double being 64 bits long. Different formats are used 
to encode doubles on various machines. These formats include TEEE, 
DECVAX, and BCD (binary coded decimal) as mentioned above; they are 
described in the entry for float. 


See Also 
data formats, declarations, float, portability 


detomw--Command 
Convert from DRI to Mark Williams format 
drtomw [-f] file ... 


drtomw converts an object, an executable object, or an archive from DRI to 
Mark Williams format. It writes the converted file into a temporary file, which 
it then writes over the original file; this will fail if the disk with the input files 
is write-protected or if the input file is set as read-only. The option -f forces 
conversion despite s possible error condition, as described below. 


drtomw generates messages to indicate to the user the type of file given as in- 
put, whether object file or archive. Normally, the format of a file cannot be 
distinguished easily by its contents; therefore, drtomw distinguishes file format 
by the suffix to the file name: relocatable objects should the suffix .o, whereas 
executable objects should have any other extension or no extension at all. 


When working with a DRI archive, drtomw first converts the archive into 
Mark Williams object archive, and then converts all of the object files within it 
to Mark Williams object files. The archive will still need a ranlib header, which 
may be added by using the command: 

ar rs archname.s rantib.sye 


drtomw converts DRI executeable files to Mark Williams format. This involves 
appending a Mark Williams format header to the end of the file. If characters 
are present beyond the end of the relocation bytes of the executeable file, 
drtomw reports this and aborts the conversion unless you use the -f (Force) flag. 


See Also 
as, a68toas, commands 
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Drvmap-Dsetdey sie 


Drvmap—bios function 10 (osbind.h) 


Dsetdry—gemdos function 14 (osbind.h) 
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Get a map of the logical disk drives 
‘include <osbind.b> 

‘include <bios.h> 

Jong Drvmap(); 

Drvmap returns a bit map of the system's logical configuration of disk drives, 
In this map, bit 0 corresponds to drive A, bit I to drive B, etc. 


Example 


include <osbind.n> 
maint) € 


int drvz 
ong drimsk=t; 
riverap = Drvmsptd: 

puts(Drives on systens\n"); 


print fcm\tdrive Zes\n, CErveiAtds 
ervmsk <= 17 


2 


> 


See Also 
bios, bit map, TOS 


Make a drive the current drive 
‘#include <osbind.h> 

long Dsetdrv(drive) int drives 
Dsetdry makes drive the current disk drive. drive can be any integer betwee 
and 15, with 0 indicating drive A, | indicating drive B, and so on through 
indicating drive P. Dsetdrv returns a bit map of the drive configuration, wit 
bits 0 through 15 indicating drives A through P. respectively; setting a bit 
indicates that the respective disk drive is present on the system, 
Example 


This example sets the default drive to 
reset to Ax. 


. Upon exiting, the default dri 


Mark Williams: 


Dsetpath 


qesicee — 


sirctude <osbind to 
Hefine DRIVEAO 
efine ORIVE ST 
Hefine DRIVEC 2 
Hefine £ DRIVE (-A6L) /* Invalid Drive Specified + 


rain C 
ong devensp; 
4 ((drivenap-DeetdrviDRIVE_5)) < 0) ¢ 
if(drivenap == £ DRIVE) 
printfeinval id drive (%e:) specified. \n™, 
(RIVE B + 1A! 
else 
BrintfC"GEMOOS error Klé\n", divensp)? 
d else ¢ 
int oevz 
long devask=t; 
prinef@current 
(ORIVE. 8 + AY) 
fortery = 0 Perv < 16; ewes) € 
‘if(devask & deivenap) 
princfe"\tdrive Zez\nm, Cdevetaty); 
domi <= 
> 
> 
3 
See Also 
Dgetdry, Drymap, gemdos, TOS. 
Notes 


‘The msh built-in function pwd and ed maintain their own idea of the current 
drive. Programs, like the example, which reset the current drive render the 
shell’s data invalid, A ed to 2 completely specified path wil fix this. 


Dsetpath—gemdos function 59 (osbind.h) 
Set the current directory 
‘#inelude <osbind.h> 
fong Dsetpath( path) char *path; 


Dsetpath sets the current directory; it returns 0 if the directory could be set, 
and non-zero if it could not. path points to the directory’s path name, which 
must be a NUL-terminated string. 

Example 

This example allows the user to set and display the default peth, or get the cur- 
rent path string for device specified. If drv equals -1, it uses the default drive 
and returns a pointer to the path buffer. 


1s 


/* Target buffer */ 
7 If drive is default */ 
7 get default drive no. */ 
(7 Put drive Letter in string */ 
hay 
77 get the rest of the path */ 
7 Return the buffer address */ 
> 
a 
* Allow default directory to be changed. 
aa 
paintarge, srav) int argcz char **arav; € 
char path (BO; 
ener “as 


char “ere; 


ffcarge < 2) € J* Wo neu path? display old */ 
‘ceons(Current path is" 
Ceonws(getpath(path,-1)); 
Cones "\r\n")? 
PremoQa; (Then exit. "7 


> 
Ccoonstnald path was 
Ceonws<getpath(path,-1))7 
Ceonasc*\r\n") 


dst = sre = arsvett; (Gee new path */ 

ff Scan for device */ 

7+ If found, set device */ 
7 Move pointer past" */ 


rv -= 1A; 

if(dey >= 0 88 dry <= 15) 
Deetdrwcdrv};, 

st = srez 


break; 


176 


dup-dup? 


FF erase f= NDE 
if ( Dsecpath(dst) != 0) € 
Ceomms("Setpath Failed, Path 2"; 


> 
> 

CeonmscuPath now set to 
Ceonus¢getpath<path, 19): 
Ceonust™\r\n") 

Ptermo0; 


? 


See Also 
‘Dgetpath, Dsetdry, Dgetdrv, gemdos, TOS 


Notes 

‘The msh functions pwd and ed maintain their own idea of the current path. 
Programs, like the example, which reset the current drive tender the shell’s data 
invalid. A ed toa completely specified path will fix this. 


dup—UNIX system call (libe-a/dup) 
Duplicate a file descriptor 
dup(/d) int fa; 


dup duplicates the existing file descriptor fd, and returns the new descriptor. 
‘The returned value is the smallest file descriptor that is not already in use by 
the calling process. fd must be less than six under TOS. 


Example 
The following example duplicates a file descriptor. 


paint) € 
int #, result; 
# 
Ff ¢cresult = dupcfayy t= -1) 
PrIntF(*file descriptor duplicated successfully \n"); 
else printfcrdupl ication unsuccessful 0; 


> 
See Also 
STDIO, UNIX routines 


Diagnostics 
dup returns a number less than zero when an error occurs, such as a bad file 
descriptor or no file descriptor available. 
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dup2 Lexicoy 


dup2—UNTX system call 
Duplicate a file descriptor 
dup2(/d, newfd) int fa, newfds 
dup2 duplicates a file descriptor. Unlike its cousin dup, dup? allows the r 
questing process to specify a new file descriptor newfd, rather than having 
system select one. If newfd is already open, the system closes it before assi 
ning it to the new file. dup2 returns the duplicate descriptor. Under TOS, 
must be greater than five, and newfd greater than six. 


See Also 
STDIO, UNIX routines 


Diagnostics 
dup2 returns a number less than zero when an error occurs, such as a bad file: 
descriptor or no file descriptor available. 1 
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Lexicon echo-edata 


echo—Command 
Repeat/expand an argument 
echo [=n] [argument ..] 


echo prints each argument on the standard output, placing a space between each 
argument, It appends @ newline to the end of the output unless the -n flag is 
present. 


If argument is a msh variable, echo will expand it before printing it. For ex- 
ample, if you type 


(es0)E echo Sele 


where <ese> indicates the escape character, echo will send the characters <ese>E 
to your terminal, which will clear the screen and home the cursor. 


See Also 
commands, msh 


ecyt—General function (libe.a/ecvt) 
Convert floating point numbers to strings 
char *eevi(d, w, dp. signp) double d; int w, "dp. *signp; 


ecvt converts d into a NUL-terminated ASCII string of numerals that is w 
characters wide; it rounds the last digit and returns 2 pointer to the result. On 
return, ecvt sets dp to point to an integer that indicates the location of the 
decimal point relative to the beginning of the string, to the right if positive, to 
the left if negative: and it sets signp to point to an integer that indicates the sign 
of d, zero if positive and nonzero if negative. ecvt performs conversions within 
static string buffers that are overwritten by each execution. 


See Also 
fevt, frexp, gevt, Idexp, modf, printf 


inker-defined symbol 
extern int edatall; 


edata is the location after the shared and private data segments. It is defined by 
the linker when the linker binds the program together for execution. The value 
of edata is merely an address. The iocation to which this address points con— 
tains no known value, and may be an illegal memory location for the program. 
The value of edata does not change while the program is running. 
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egrep—Command 
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Example soteatias 
For an example of this function, see the entry for memory allocation, 
See Also 

end, etext 


‘Extended pattern search 
egrep [option ...] [pattern] [file .} 
egrep searches each file for occurrences of pattern (also called a regular expr 
sion). If no file is specified, it searches the standard input, Normally, it pri 
each line matching the pattern, 
The simplest patterns accepted by egrep are ordinary alphanumeric strit 
egrep can also process patterns that include the following wildcard characters: 
* Match beginning of line, unless it appears immediately after ‘f ( 
below), 


$ Match end of line, 
Match zero or more repetitions of preceding character. 
Match any character except newline. 


chars} 
Match any one of the enclosed chars, Ranges of letters or digits may be 
indicated using *-" 

(chars) 
Match any character except one of the enclosed chars. Ranges of letters or 
digits may be indicated using *~ 

\e Disregard special meaning of character c. 


| Match the preceding pattern or the following pattern. For example, the 
pattern catldog matches either cat or dog. A newline within the paitern 
has the same meaning as‘. 


4 Match one or more occurrences of the immediately preceding pattern 
element; it works like “**, except it matches at least one occurrence in- 
stead of zero or more occurrences. 


2 Match zero or one occurrence of the preceding element of the pattern. 


(.) Parentheses may be used to group patterns, For example, (Ivan)+ 
matches a sequence of one or more occurrences of the four letters ‘I’ 'v" 


Because the metacharacters ‘**, +7", ‘8’, (,")', ‘T, ‘T., and’ are also special to the 
micro-shell msh, patterns that contain those ‘characters must be quoted by 
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sesicon end 


enclosing pattern within double quotation marks. 
The following lists the available options: 


-b With each cutput line, print the block number in which the line started 
(used to search file systems). 


-¢ Print how many lines match, rather than the fines themselves. 
~e The next argument is paitern (useful if the pattern starts with ‘-"). 


-f The next argument is a file that contains a list of patterns separated by 
newlines; there is no pattern argument 


-h When more than one file is specified, output lines are normally accom 
panied by the file name; ~h suppresses this. 


1 Print the name of each file that contains the string, rather than the lines 
themselves, 


-n The line number in the file accompanies each line printed. 
Suppress all output, just return status. 
Print a line only if the pattern is not found in the line. 


-y  Lower-case letters in the pattern match lower-case and upper-case letters 
on the input lines. A letter escaped with ‘/* in the pattern must be 
matched in exactly that case. 


See Also 
commands 


Diagnostics 

‘egrep returns an exit status of 0 for success, | for no matches, and 2 for error. 
Notes 

egrep uses a deterministic finite automaton (DFA) for the search, It builds the 
DFA dynamically, so it begins doing useful work immediately. This means that 
egrep is considerably faster than other, earlier pattern-searching commands, on 
almost any length of file. 


inker-defined symbol 
extern int end] |; 


end is the location after the uninitialized data segment; it is defined by the 
linker when the linker binds the program together for execution. The value of 
end is merely an address. The location to which it points contains no known 
value, and may te illegal memory locations for the program. The value of end 
does not change while the program is running. 
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Example 
For an example of this function, see the entry for memory allocation. 


See Also 
edata, etext 


‘An enum declaration is a data type whose syntax resembles those of the struct 
and union declarations, enum declares a type and a set of identifiers that can be 
used as values for objects of the declared type. For example, 


enum opinion (yes, maybe, no) guess; 


declares an enumerated type opinion with three values: yes, no, and maybe. It 
also declares a variable of type opinion enum guess. guess may only have a value 
of either yes, no, or maybe. As with a struct or union declaration, the tag 
{opinion in this example) is optional; if present, it may be used in subsequent 
declarations, After the above declaration, the statement 


register enum opinion *op; 
declares a register pointer to an object of type opinion, 


All identifiers in an enumeration declaration must be distinct from other iden— 
tificrs in the program, ‘The identifiers act as constants and may appear 
wherever constants are appropriate. Mark Williams C assigns values (0 the 
identifiers from left to right, normslly beginning with 0 and increasing by 1. 
The values often are ints, although if the range of values is small enough, the. 
enum will be an unsigned char. If an identifier in the declaration is followed by 
‘an equal sign and a constant, the identifier is assigned the given value, and sub~ 
sequent values increase by 1 from that value. 
To add enum to the formal definition of C, amend the list of type-specifiers in 
Appendix A of The C Programming Language to include enum-specifier, and 
add the following syntax: 
enum-specifier: 

enum ( enum-Hist ) 

enum identifier ( enum-list ) 

enum identifier 


enum-list: 
enumerator 
enum-list , enumerator 
enumerator: 
identifier 
identifier = constant-expression 
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See Also 
declarations 


environ—Definition 


extern char "environ; 


environ is a pointer set by the run-time start-up routine. It points to the en- 
vironment vector, which is equal to the third argument passed to main, char 
*enypl|: this, in turn, is the handle that the function geteny uses to find the en- 
vironment, 


Example 

For an example of how this element is used in a C program, see the entry for 
memory allocation, 

See Also 

ewp 


Definition 
Variable passed to main 
char *enypl|; 


enyp is an abbreviation for environmental parameter, It is the traditional name 
for a pointer to an array of string pointers passed toa C program's main func- 
tion, and is by convention the third argument passed to main 

Example 

For an example of this function, see the entry for memory allocation, 

See Also 

ange, argy, main 


EOF—Manifest constant 
EOF js an acronym for “end of file"; it is the manifest constant defined in 
stdio.h that is used to signal that the end of a file has been reached, 


To signal EOF to a program reading from the console keyboard under TOS, you 
should type <etrl-Z» followed by <RETURN> on a line by itself. <ctrl-Z> as 
an EOF signal is implemented by the read routine. Programs that use TOS calls 
to read the console must implement an EOF signal themselves. 


Example 
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Hinclude <stdio.h> 
maine? € 
int e7 
hi Lecce=getchar¢))!=£0F) 
putehar(e?? 


> 


See Also 
manifest constant, stdio.h 


errno—UNIX data (erts0.0) 
External integer for return of error status 
extern int errno; 


errno is an external integer that is set to the negative value of any error status 
returned by TOS to the UNIX system call emulation routines. The routine per= 
ror() Se tie. array of string sys_errlist may be used to provide a textual trans- 
lation of errno. 


Mathematical functions also use ermo to indicate classifications of errors on 

return, It is defined within the header file errno.h, Because not every function 
uses errno, it should be polled only in connection with those functions that 
document its use and the meaning of the various status values, 


‘The error codes returned by TOS are listed in the entry for error codes, below. 


See Also 
errno.h, error codes, mathematics library, perror, UNIX routines 


errno.h—Header file 
Error numbers used by errno function 
#include <errno.h> 


errno.h is a header that defines and describes the error numbers returned by er= 
no, 

See Also 

errno, header file, TOS 


error codes—Definition 
“The following lists the error codes returned by TOS: 


BIOS-level errors: 


AE_OK OL OK, no error 
AERROR IL basic, fundamental error 
AEDRVNR -2L drive not ready 
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AEUNCMD 3L 
‘AE_CRC =a 
AEBADRQ -SL 
AE_SEEK -6L 
AEMEDIA -7L 
AESECNF “8 
AEPAPER -9L 
‘AEWRITE -10L 
AEREADF -HL 
AEGENRL -120 
AEWRPRO. -13L 
AE_ CHING -1aL 
AEUNDEVY -15L 
AEBADSF -16L, 
AEOTHER -17L 

GEMDOS-level errors: 
AEINVEN 32k 
AEFILNE -33L 
AEPTHNE -34L 
AENHNDL. -35L 
AEACCDN -36L 
AETHNDL -37L 
‘AENSMEM. -39L 
‘AEIMBA -40L. 
AEDRIVE 46L. 
AEXDEV 248 
AENMFIL ~49L 

Miscellaneous error codes: 
AERANGE ~64L 
AEINTRN -65L 
AEPLFMT -66L 
AEGSBF -67L 

See Also 


errno, errno.h, perror 


etext—Linker-defined symbol 
extern int etext{]; 


etext is the location after the shared and private text (code) segments; 


unknown command 
CRC error 

bad request 

seek error 
unknown media 
sector not found 


no paper 
write Fault 

read fault 

general error 

write protect 

media change 
unknown device 

bad sectors on format 
insert other disk 


invatid function number 

fite not found 

path not found 

too many open files no handles left 
access denied 

invalid handle 

insufficient memory 

invalid memory block address 
invalid drive was specified 

cross device rename not documented 
no more files 


range error 
internal error 

invalid program load format 

setblock failure due to growth restrictions 


t is 


defined by the linker when it binds the program together for execution, The 
value of etext is merely an address. The location to which it points contains no 
known value, and may be illegal memory locations for the program. The value 
of etext does not change while the program is running 
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evnt_button Lexier 


Example 
For an example of this function, see the entry for memory allocation. 


See Also 
edata, end, malloc 


evnt_button—AES function (libaes.a/evnt_button) 
‘Await a specific mouse button event 
#include <aesbind.h> 
int evmt_button(clicks, button, state. record) 
int clicks, button, state; Mouse record; 


evnt_button is an AES routine that waits for a specified button event. clicks is. 
the number of clicks to await. bution is the number of the button to awail 
counting from the left, as follows: Ox!, leftmost button; 0x2, second from lel 
Ox4, third from left; etc. 


state ig the button state to await: zero indicates up and one indicates down, 
evnt_button returns zero if an error occurred, and a number greater than zero. 
if one did not. 


record points to where evnt_button writes the result of a button event. It is 
declared to be of type Mouse, which is a structure of four pointers to integer 
that ig declared in the header file aesbind.h, as Follows: 1 


x X coordinate of mouse pointer 
y Y coordinate of mouse pointer 
b button state when event occurred 
k state of control, alt, and shift keys, OR'd together: 
x0; all Keys up 
OxI: right shift key down 
Ox2: left shift key down 
0x4: contro! key down 
Ox8: alt key down 


evnt_button returns the number of times the button entered the desired state. 


Example 
For an example of this routine, see the entry for v_ei 


See Also 
AES, TOS 


Notes 
‘Note that this routine can be told only to wait for one specified button event, 
e.g. for button | alone, If you attempt to tell it to wait for button | or button 
2, it will react as if you told it to wait for button 1 and button 2, i., for both 
buttons to be pressed simultaneously. 
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eynt_delick—A ES function (libaes.a/evnt_dclick) 


cevnt_keybd—AES function (libaes. 


~ Get/set double-click interval 
#include <aesbind.h> 
int evnt_dclick(speed. getset) Int speed, getset; 


evnt_delick is an AES routine that gets or sets the mouse's double-click speed. 
speci is the double-click speed, from zero through four, with zero being the 
siowest and four the fastest. It is ignored if getsct is set to zero. gotset is a flag: 
zero tells AES to return the current speed, and one tells it to set the new speed. 
evnt_delick returns the old click speed (if getset is set to, zero) or the new click 
speed (if it is set to one), 


See Also 
AES, TOS 


Await a keyboard event 
#include <aesbind.h> 
int evnt_keybd() 


eynt_keybd is an AES routine that awaits a keyboard event; in other words, it 
Waits for the user to press a key on the keyboard. evnt_keybd returns the code 
of the key pressed. 

Example 

‘The following example prints out the scan code for each key pressed. Pressing 
the <return> key exits, 


include <eesbind.t> 
include <gemiefs.t> 
feof ine RETURN OxTCOD 
maine) € 

unsianed ers 


oppl_init; 


_ beybd0); 
sul tehtiey) ¢ 
‘case RETUR 
‘ppl_exit; 
exit00; 
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etoults 
printfcrThe scan code Te: Ax\n", key)? 
break; 


> 
> 

See Also 

AES, keyboard, TOS 


evnt_mesag—AES function (Iibaes.a/evnt_mesag) 
‘Await a message 
#include <aesbind.h> 
int evmt_mesag(tuffer) char *buffer; 
evnt_mesag is an AES routine that awaits a message. buffer points to where the. 
message is to be written. 


GEM uses 12 predefined messages to pass information among its appli 
Each message is eight ints long, and has the following structure: 
0 Type of message 
1 Handle of application 
2 Number of extra bytes in message; ie, 
number of bytes beyond 16 
3-7 Contents of message 


The following lists the predefined messages by the value of word 0, as defined: 
in the header file gemdefs.h; 


MN_SELECTED (menu selected) Word 3 gives the number within its object 


tree of the title of the selected menu, and word 4 gives the 
number of the selected item, 


WM_REDRAW (redraw a window) Word 3 gives the window's handle; 
words 4 through 7 give, respectively, the X coordinate, the 
Y coordinate, the width, and the height of the window to be 
drawn. 


WM_TOPPED — (make a window the topmost window) Word 3 gives the 
window handle. 

WM_CLOSED —_(close-window box clicked) Word 3 gives the window's 
handle. 


WM_FULLED —_(full-window box clicked) Word 3. gives the 
handle. 


window's 
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WM_ARROWED 


WM_HSLID 


WM_VSLID 


WM_SIZED 


WM_MOVED 


AC_OPEN 
AC_CLOSE 


evmt_mesag always 


Example 
For an example of 1 


See Also 
AES, TOS, window 


eynt_mouse—AES functior 


(arrow or scroll bar clicked) Word 3 gives the window's 
handle. Word 4 gives the action requested, as follows: 

Page up 

Page down 

Row up 

Row down 

Page left 

Page right 

Column left 

Column right 


(horizontal slider moved) Word 3 gives the window's handle. 
Word 4 gives the slider’s position: zero indicates the leftmost 
position, and 1,000 the rightmost. 


Saneunso 


(vertical slider moved) Word 3 gives the window's handle, 
Word 4 gives the slider's position: zero indicates the leftmost 
position, and 1,000 the rightmost. 


(window size altered) Word 3 gives the window's handle. 


Words 4 through 7 give, respectively, the X coordinate, the 
Y coordinate, the new width, and the new height. 


(window position altered) Word 3 gives the window's 
handle. Words 4 through 7 give, respectively, the new > 
coordinate, the new Y coordinate, the width, and the 
height, 


(desk accessory opened) Word 3 gives the desk accessory"s 
menu item identifier, as set by the function menu_register. 


(desk accessory closed) Word 3 gives the desk accessory's 
menu item identifier, as set by the function menu_register, 


returns one. 


his routine, see the entry for window. 


n (libaes, 


a/eynt_mouse) 


Vait for mouse to enter specified rectangle 
clude <aesbind.h> 


Int evmt_mouse(inout, rectangle, record) 
int inoulj Reet rectangle; Mouse record; 
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multi 
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evnt_mouse is an AES routine that waits for the mouse pointer to enter or leave 
a specified rectangle on the screen, inout tells AES whether to wait for U 
pointer to enter (zero) or leave (one) the rectangle, Note that the screen 
manager constantly checks the location of the mouse; it is more accurate to say 
that evnt_mouse waits for the mouse pointer to be found inside or outside the. 
rectangle, 


rectangle is of the type Rect, which is defined in the header file aesbind.h, Reet 
consists of four element 


xX coordinate of rectangle 
y  ¥ coordinate of rectangle 
w width of rectangle 

h height of rectangle 


record points to where evnt_mouse writes the result of a mouse button event, It 
ig declared to be of type Mouse, which is a structure of four pointers to in 
tegers. Mouse is declared in the header file aesbind.h, as follows: 


X coordinate of mouse pointer 

Y coordinate of mouse pointer 
button state when event occurred 
state of control, alt, and shift keys: 
Ox0: all keys up 

Ox1: right shift key down 

0x2: left shift key down 

Ox4: control key down 

Ox8: alt key down 


wewx 


‘evnt_mouse always returns one. 


See Also 
AES, TOS 


multi—AES function (Iibaes.a/evmt_multl) 
‘Await one or more specified events 
#include <aesbind.h> 
int evnt_multl(events, clicks, button, state, mlinout, rectangle! 
‘mainoul, reclangle2, &buffer, lowtime. hightime. record, key. times) 
int events, clicks, button. state, minout. m2inout, lowtime, hightime, 
Rect rectangle!, rectangle2; Mouse record; long buffer; int *key, *times; 


eynt_multi is an AES routine that awaits one or more of a set of events. It 
‘one Of the most complex AES functions, and the one most commonly used. 


events is a flag that indicates the events for which the process is waiting, 
follows: 


Lexicon evnt_multi 


0x01 keyboard event 

0x02 mouse button event 

Ox04 first defined mouse event 
0x08 second defined mouse event 
0x10 message from another process 
0x20 timer event 


clicks is the number of mouse button clicks the process is awaiting. Auton is a 
mask of the number of the mouse button that the processing is awaiting, from 
fone to 16 (as counted from the left): Ox! indicates the leftmost button; 0x2, the 
button second from the left, Ox4, the button third from the left, etc. Note that 
as of this writing no mouse has more than three buttons. state is the button 
state being awaited: zero indicates up, and one indicates down. 


evnt_multi can await either or both of two mouse events. m/inout indicates 
that the process is waiting for the mouse pointer to enter (zero) or exit (one) the 
first mouse rectangle. Note that the screen manager is constantly polling the 
screen to check the location of the mouse; it is more accurate to say th 
evnt_multi waits for the mouse pointer to be found inside or outside the rec- 
tangle. rectangle! defines the area on the screen to be watched. It is declared 
to be of type Reet, which is declared in the header file aesbind.h; Rect consists 
of four elements, as follows: 


X coordinate of rectangle 
y  Y coordinate of rectangle 
width of rectangle 

height of rectangle 


m2inout and rectangle? define the second mouse event being awaited; they are 
defined in exactly the same manner as mJinout and rectangle. 


buffer is the space into which AES writes any message from another process. 


lowtime and hightime are, respectively, the low word and the high word of the 
time interval that the process will wait before it “times out", in milliseconds. 


record points to where evat_multi writes the result of 2 mouse button event, It 
is declared to be of type Mouse, which is a structure of four pointers to integers 
that is declared in the header file aesbind.h, as follows: 
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X coordinate of mouse pointer 
Y coordinate of mouse pointer 
button state when event occurred 

state of control, alt, and shift keys: 0=up, 
x0: all keys up 

Ox1: right shift key down 

x2; left shift key down 

0x4: contro! key down 

Ox8: alt key down 


weer 


If keyboard event occurs, key’ points to the code of the key pressed. See th 
entry keyboard fora table of the key codes. 


Finally, times points to where to number of times the mouse button entered the 
desired state. 


‘eyat_mulli returns a number that indicates which event occurred, encoded in 
the same manner as the variable events, above, 


Example 

example demonstrates how to use evmt_multi, Tt displays a 
mouse pointer changes from an arrow to a bumblebee when it moves from in- 
side to outside the window. The program exits when a key is typed. 


Aineluse <nesbind.h> 
Winclude <gondet she 
int nowhere = 0 


7* place for unused pointers to point at */ 


rine) ¢ 
PP declarations for window */ 
nt handle; 
char “title =" 11TLe *; 


1 declarations for ent multicy */ 


int select ion; 77 code for event that occurred */ 

rslgned int saich = OR [92 

int clicks = 1; 7* runber of clicks expected on mouse button */ 
int button = 1; @ sbich button; t+ leftmost */ 


Int buttenstare 7% button state expected; 0 = down */ 
(7 Ast mouse event: 0 = into rectangle 

7 cectangle for both mouse events */ 

7 someplace for rectangle to cone fron * 

[7 2nd mouse event: 1 = out of rectangle 

nt *butfer = Enouhere; 77 buffer for messages; not used here */ 

int Lowt ine = nowhere: 1% (ow word for timer event; not used here */ 
int hightime = paubere: ‘ot used rere */ 


(2 wien Key wes pressed; not used here */ 
77 fe. of ties neue button entered stare */ 
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(J initialize rectangles used, in rasters */ 
bigrect.x = 210; 
bigreet-y = 100; 
bigrect.¥ = 220; 
bigrect-h = 200; 


porect.x = 0; 
orecth = 0; 
rorect a 

erect sh 


/* initialize place, although not used here * 
placer = place.y = place.b = place.t 


Inshore; 


appt_init 
handle = wind create(Mane, bigrect); 
Wind. set¢handie, WF_MAME, tT ele, 0,09; 
Braf_groubox(norect, bigrect); 

Wind openthandle, bigrect); 


‘election = aunt multi(ubieh, clicks, button, buttonstate, 
imo, bigrect, autot, bigrect, buffer, lovtine, 
hightine, place, key, Btimes); 


awitch¢selection) ¢ 
case WU XEYBO: 
od_clouechandle); 
nrinkbox(nerect, Biarect); 
AIR; 
exit); 
‘grat _nouse( ARRON, nowhere’ 


E, tnouhor ed 


y 
y 

5) 

See Also 

AES, keyboard, TOS 

Notes 


Note that, with regard to button events, you can tell evn{_multi to wait only for 
one specified event, e.g., for button | 10 be pressed. Ifyou tell it to wait for 
‘button 1 or button 3 to be pressed, it will act as if you told it to wait for button 
and button 2 to be pressed, which the hardware cannot handle. 
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‘eymt_timer—AES function (libaes.a/evmt_timer) 
Wait for a specified length of time 
#include <aesbind.h> 
int evat_timer(lowtime, hightime) int lowtime. hightime: 


eynt_timer is an AES routine that awaits a timer event, ie., that waits for 
given length of time to pass. The time interval to wait before “timing out” 
siven in milliseconds, Jowtime is the low word of the time interval, 
hightime is the high word. evnt_timer always returns one, 

See Also 

‘AES, TOS 

Notes 

As of this writing, using evat_timer within a desk accessory will cause the 
tem to crash if the desk accessory performs any calls (0 a BDOS routine, For 
‘more information on BDOS, see the entries for VDI and metafile. 


executable file—Definition 
‘An executable file is one that can be loaded directly by the operating syst 
and executed. Normally, an executable file is one that has gone through both 
the compilation phase, where it has been rendered into machine language, and 
the link phase, in which the compiled program has all operating system-specific 
information added and all library functions are copied into the program. 


See Also 
Tile 


exeeve—UNIX system function 
Int execye—Execute a command 
exeeve( file, arg, env) 
char *file, “argu, "enl] 


execye permits you to tell to TOS execute a specific command, This is doné 
through the GEMDOS call Pexec. The calling program is suspended while 1 
command is being executed; the calling program returns when the command 
finished executing. file is the complete path name of the file to be executed, 
argv points to a list of arguments to be passed to the command, env points toa 
list of status environmental parameters, If the Pexee status is negative, then e 
roo is set to the absolute value of the status. 
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See Also 
environment, Pexee, system 


exit Command 
Exit from msh 
exit [status] 


exit terminates the shell msh, msh executes exit directly. The optional argu- 
ment status is an integer which is returned as the exit status. 

See Also 

commands, msh 


exitGeneral function (Iibe.a/exit) 
Terminate a program directly 
int exit(status) int status; 


exit terminates a program gracefully. It flushes all buffers, closes each open 
file, and then returns the given status. Some systems, such as the Series TIT un- 
der ISIS, throw away the exit, On TOS, it is returned to the parent program as 
the result of Pexec. 


See Also 
exit, runtime startup, system, UNIX routines 
The C Programming Language, page 154 


exit—UNIX system call (libe.a/_exit) 
Terminate a program directly 
_exlt(staus) Int status; 
_evit terminates a program, It returns status to the calling program, and never 
returns, 


See Also 

exit, Pterm, runtime startup, system, UNIX routines 

Notes 

Programs should normally terminate via exit, which flushes buffered 1/0 and 
closes associated files. Note that on the Atari ST, _ exit is implemented via the 
function Perm. 


exp—Mathematics function (libm.a/exp) 
Compute exponent 
#include <math.h> 
double exp(=) double =; 
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extern 


exp returns the exponential of =, or e* 


Example 
‘The following example demonstrates exp: 


include <nath.he 


4 Gerrne) 
perror¢naney; 


else 
printfematog Xen", value, named; 
errno = 0; 
) 


fidetine disploy(x) dodisptayecdoubleycad, 4) 


maint) € 
‘extern chi OF 
double x: 
char atringi6l; 
fores3) « 
prinef("Enter pumbers "2; 
Hfegetecatring) == 0) 
break; 
x» acotestringy; 
disphay(ad; 
displaycexp0)? 
Sisptay(pou(10.0,40)7 
Sisplay( (oglexp(3))); 
‘display legt0¢powe 10 
a 
> 
See Also 


errno, mathematics library 


Diagnostics 
exp indicates overflow by an errno of ERANGE and a huge returned value, 


extern—Definition 
extern indicates that a C element belongs to the external storage class. 
variables and functions may be declared to be extern. extern symbols | 
“visible” outside of the source file of definition. All functions and all dal 
defined outside of functions are implicitly extern unless declared static, 


When a source file references data that are defined in another file, it_mu 
declare the data to be extern, or the linker will return an error message of 
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form: 
Undefined symbol name 

For example, following declares the array tzname: 
extern char tarane (21 (523; 


When a function calls a function defined in another source file or a library, it 
should make an extern declaration of the function. In the absence of a declara- 
tion, extern functions are assumed to return ints, which may cause serious 
srablems if the function actually returns a 32-bit pointer, a tong tat, or @ 
double. 


See Also 
auto, pun, register, static, storage class 
The C Programming Language, pages 28, 72, 204 
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fabs—Mathematics function (libm.a/fabs) 


Fattrib—gemdos function 67 (osbind.h) 
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Compute absolute value 
#include <math.h> 
double fabs(=) double 2; 


fabs implements the absolute value function. It returns = if 2 is zero or posi 
tive, or ~> if = is negative, 


Example 
For an example of this function, see the entry for ceil, 


See Also 
abs, ceil, floor, frexp, mathematics library 


Get and set file aitributes 

Winclude <osbiad.h> 

long Fattrib(name, readset, setatrib) char *name; 
int readset, setatriby 


Fattrib gets and sets file attributes. name points to the file’s name, which must 
be a NUL-terminated string. readset contains a 0 if you wish to read the file's 

attributes, or a 1 if you wish to set them. sevarrib contains an integer than en= 
codes the file's attributes, as follows; 0x01, read only; 0x02, hidden from direc~ 
tory search; Ox04 set to system, hidden from directory search; 0x08, contains 
volume label in first 11 bytes; 0x10, file is a subdirectory; and 0x20, file has 
been written to and closed, Fattrib returns the file's attributes if they have 
been read successfully; otherwise, it cannot be relied on to return meaningful 
information, 


Example 


Binetude <osbind.h> 
extern int errno; 


chor “erreablen = 
read only", 
hidden, 
eystem Filet, 
volume Label, 
subi rectory®, 
“eritten to and closed 
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nointarae, argv) int sree; char **aravs © 
Unsigned attribs; 
unsigned point; 
int § 


if carge <2) € 
printf(lusage: Fattrib #iLe\n9; 
Preract 
> 
if (Cattribe = rattribtaravit1, 0, 09) < 0) ¢ 
printf(an't Fatteib file a —\e", argett3)5 
errno = -attri 
perrorcerattrib failure"); 
Prermt); 
> 
printf(vFite ein, revit); 
14 (atteibe == 0)'¢ 
rint#(" normal #ie\n! 
Perma; 
> 
point = 1; 
for (10 3 <6 5 (99) ¢ 
14 (point & attrib 
prinefo" (Ray", atreabletiiy; 
point <e: 1) 
> 
prinet ney; 
> 
See Also 
gemdos, TOS 


{elose—STDIO Function (Iibe.8/felose) 
ose stream 
#include <stdio.h> 
Int felose( /p) FILE */p; 


felose closes the stream fp. It calls fflush on the given Jp, closes the associated 
file, and releases any allocated buffer. The library function exit calls felose for 
open streams. 


Example 
For examples of how to use this function, see the entries for fopen and fseek. 


See Also 
STDIO 
The C Programming Language, page 153 
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Felose—gemdos function 62 (osbind.h) 


Fereate—gemdos function 60 (osbind.h) 
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Diagnostics 
felose returns EOF on error. 


Close a file 

#include <osbind.h> 

long Felose(handle) int handle; 

Felose closes a file. handle is the file handle that was returned by Fopen 
Fereate(), Fdup(), or inherited by the process. Felose returns 0 if the file coul 
be closed, and non-zero if it could not, 
Example 

For example of how to use this macro, see the entries for Fseek and Fereate. 
See Also 

gemdos, TOS 


Create a file 
#include <osbind.h> 
long Fereate(name, type) char *name; int type; 


Fereate creates s file. name points to the file’s path name, which must be 
NUL-terminated string, type contains a number that encodes the file's at- 
tributes, a5 follows: 0x0), read-only; 0x02, hidden from directory search; 0x04, 
set to system, hidden from directory search; and 0x08, contains volume label in 
first 11 bytes. Fereate returns a file handle, which is understood by TOS. 
Example 
‘The following example, when compiled, takes two arguments, file! and ile2; it 
then copies file/ into file2. If file? does not exist, it is created. 


Lexicon Fereate 


Hirelude <osbind. n> 
Firelude <stdio.h> 
#ireluse <stat.h> 
extern int errno: 


rnain¢erge, argv) int argc; char **argvi C 
int status; 
int 
int 
‘struct DAABUFFER “mts; 
cher “buffer; 
long copysize; 


if Carge <3) 
‘Ceonws( usage: Fereate source target\r\n"); 
Perm); 

> 


Hf CCirhand = Fepentargvttl, 09) € 0) & 
fprinttCetderr,"\ntan't open input file %e",srgvttl; 
perror("Fopen failure’); 


Prerm 1); 
> 
Foatdta(mydtas(etruct OMABUFFER *)mullocCelzeot (struct OMABUFFER))); 
if (Cetarusctstiest(aravtt], OxF79) I= 0) 
FetoseCirhand); 
tprinttCetderr,"\nError getting state on input file Xs 
srovttd: 
perror(sfeticst failure’) 
Prarmty: 
ey 


stetus = mydtard fartr & 7 


(t¢Couthand « Fereatecargvi2}, status?) <0) ¢ 
Felose¢irhend) 
forintfCatderr,"\ncan't open output file Xe argvi21); 
errno = -outhand; 

perror(Hfereste 
Prermct); 


failed); 


Mark Williams C 201 


202 


(char * mal Loc4096): 


copysize = mydte-rd fsize: 
while Ccopysize>s0) ¢ 
if (CstatussFreadcinhand, GOv6L, buffer)) €0) ¢ 


Felosecinhsrd) ; 

Feloseouthand); 

Foeletetargvt21); 

Aprint (stderr, "\nieed error on 88", aravithys 
‘ereno = ~statuey 

perror(*ead failure); 

Prera(); 


{4 (Cetatussfuritecouthond, 6096L, buffer? <0) ¢ 
Felesecinhand); 
Fetesetouthere 
Fdeletecargv(21); 
fprintf(stderr, *\nirite error on file X6%, argvt21)s 
errno = «status: 
perroccmrite failures): 
Perec); 


> 
copysize == 4096; 


> 
it (eopysize > 0) ¢ 


if (CetatussFresd(inhand, copysize, buffer) <0) ¢ 
Feloset\ehand): 
FeloseCouthand): 
Feetevecargv(2)), 
{print (stderr, "\ntead error on X6", aravitl); 

rn = ~status; 
percor(*Reed failure); 
erm) 


> 


(f (cetarussrweltecouthard, copysize, buffer)) « 0) ¢ 
FeloseC inane): 
Fetosetouthand); 
Poel etecergvi2i; 
Aprintt(steerr, 
errno = status, 
perror(ovrite fajture"): 
Preract); 


‘\ndrite error on Xs", aravi21); 
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FeloseCinhend) 
Felosetouthand): 

printfCHFile Xs copied to file Xe.\n", 
Freetayat 

FsetacacwuLl: 

PrermOoo; 


See Also 
gemdos, TOS. 


fet General function (libe.8/fevt) 
Convert floating point numbers to ASCII strings 
char *fevt(d, w, dp, signp) double d; int w, *dp, *signp; 


fevt converts floating point numbers to ASCII strings. fert converts d into a 
NUL-terminated string of decimal digits that is w characters wide. It rounds 
the last digit and returns a pointer to the result. On return, fevt sets dp to point 
to an integer that indicates the location of the decimal point relative to the 
beginning of the string: to the right if positive, and to the left if negative. Fin- 
ally, it sets signp points to an integer that indicates the sign of d: zero if pos 

tive, and nonzero if negative, fevt rounds the result to FORTRAN F-format. 


See Also 
ecvt, frexp, gevt, Idexp, modf, printf 


Notes 
feyt performs conversions within static string buffers that are overwritten by 
each execution. 


Fuatime—gemdos function 87 (osbind.h) 
Get or set a file's date/time stamp 
include <osbind,h> 
void Fdatime(info, handle getset) 
int handle, getset. infol2k 


Féatime retrieves or sets a file's time/date stamp. handle is the file's handle 
that was set when the file was first opened. getset indicates whether the stamp 
ig to be reset or retrieved: 0 indicates get, and 1 indicates set. info points toa 
buffer that holds two integers; this buffer either have the time/date stamp writ- 
ten into it, or will hold the new time/date stamp that is to replace the previus 
stamp, depending on whether the stamp is to be retrieved or reset. In either 
case, the first integer of info encodes the time and the second integer encodes 
the date, as follows: 
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infotl] 0-4 no, of two-second increments (0-29) 
5-10 no, of minutes (0-59) 
1-15 no, of the hour (0-23) 
infof2] 0-4 day of the month (1-31) 
5-8 no. of the month (1-12) 
9-15 no. of the year (0-119, 1980 = 0). 
Faatime returns nothing. 
Example 


‘The following example demonstrates Fdatime. 


Hinelide <osbind.h> 
Hinclude <errno.h> 
Winelude <tjme.h> 


mincarge, wrgv) 
Int arge; ‘char argv; ¢ 


int dz 

rtetd t rte; /* Bactvarde tine, date */ 
utetdt utd; 7° Forwards date, tine */ 
tine t (/ CORERENT tine */ 

tat tp; 0 Tse flelde "7 


$f (arge <2) ¢ 

printf("usage: Fdatine <fijename>\n"); 

exit; ( 
5 


1H C16 = Fopencaravind, 099 <0) ¢ 


perrorcargvit}): 
exit; 


tp = fetd to tmcut 
T= joay to timectm to_iéay¢ep)); 


Printfcrxst, asctime(tp)); 
printf(rxem, ctimecht)); 
return 0; 

> 


‘See Also 
gemdos, TIMEZONE, TOS 
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Nores 

ash updates the time it returns by one hour if the daylight savings time flag is 
set in the TIMEZONE environmental parameter. Therefore, during the sum- 
mer months, the time returned by this routine may be one hour behind the time 
returned by the date command. 


Ficlete—gemdos function 65 (osbind-h) 
Delete a file 
sinclude <osbind.h> 
long Féelete(name) char "nam 


Fdelete deletes a file. name points to the file's name, which must be a NUL~ 
terminated string, Fdelete returns 0 if the file could te deleted, and non-zero 
if it could not. 


Example 

For examples of how to use this macto, see the entries for Fseek and Fereate, 
See Also 

mios, TOS 


Fdup~gemdos function 69 (osbind.h) 
Generate a substitute file handle 
vinclude <osbind.h> 
long Fdup(handle) int handle; 


Fdup generates a substitute file handle for a standard file handle: between one 
and five, inclusive. It returns the new, non-standard file handle if successful, 
ar the error code EINHNDL (invalid handle) or ENHNDL (no handles left, i... 
too many files open) if not. 


See Also 
gemdos, TOS 


Notes 

Fuup returns with no error indication if the argument it is passed is a file 
handle that has been processed by Felose; however, the system will generate an 
address error when the process terminates. 


feof—STDIO macro (stdio.h) 
Discover stream status 
#include <stdio.h> 
feof(/n) FILE */r, 
feof isa macro that tests the status of the argument stream fp. It returns a num- 
ber other than zero when fp has reached the end of file, and 0 otherwise. One 
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use of feof is to distinguish a value of -1 returned by getw from an EOF. 


Example 
For an example of how to use this function, see the entry for fopen. 


See Also 
STDIO 


ferror—STDIO macro (stdio-h) 
Discover stream status 
include <stdio.h> 
ferror(/p) FILE */ps 


ferror is @ macro that tests the status of the argument stream fp. It returns al 
number other than zero if an error has occurred on /p. Any error condition the 
is discovered will persist either until the stream is closed or until clearerr ig 
used to clear it, For write routines that employ buffers, fflush should be called 
before ferror, in case an error occurs on the last block written. 
See Also 

STDIO 


fflush—STDIO function (libe.a/ffush) 
Flush stream output buffer 
‘itinclude <stdio.h> 
fflush(/p) FILE */p; 
{flush writes any buffered output data associated with the stream /p. The 
stays open after fflush is called. felose calls fflush; there is no need for the user 
program to call it directly under ordinary conditions 
Example 
For an example of this routine, see the entry for v_gtext, 


See Also 
STDIO 


Diagnostics 
{flush returns EO 


it cannot flush the contents of the buffers. 


Fforce—gemdos function 70 (osbiad.h) 
Force a file handle 
#include <osbind.h> 
long Fforce(shandle. nshandle) int shandle nshandle; 


Fforce forces the standard file handle, ie., zero through five, to point to the 
same file as the non-standard file handle, ie., six and up. Fforce returns 
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E_OK (no error) if successful, or ENDL (invalid handle) if not. 


See Also 
Faup, gemdos, TOS, 


fgete—STDIO function (libe.a/fgetc) 
Read character from stream 
#include <stdio.h> 
int fgete(/p) FILE */p: 


fgete reads characters from the input stream fp. It is a function whose body is 
the macro gete. In general, it behaves the same as gete; it runs more slowly than 
ete, but yields a smaller object module when compiled. 


Example 
‘This example counts the number of lines and “sentences” ina file. 


Winetuse <etdlo.he 
malnee 
FILE "4; 
int ch, nines, sent 
int f Lenane 20); 
lines = ments = 
prinetcventer fle fo tests 
eta ti(ensned: 
Tf (fp = fopencfitename,*")) 1 MULL) 
Wsite ((eh = fgetec tp)? I» EOF) ¢ 
Wf (ch ae N\nt) sank ines; 
fete teh ee tt |] ehae 18 |] eh se 1719 


14 (ooh = faetecteny t= 1.1 ¢ 
wreeteteh, fede 

5 

‘else forterst 


5 Cehefgetectpd beet.) 


> 


> 
Printtcund Line(e), Xd sentence(s).\n, lines, sents); 
D else 


printftnCennot open Xe.\nt, filename); 


> 
See Also 
gete, STDIO 


Diagnostics 
{gete returns EOF at end of file or on read error. 
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Fgetdta—gemdos function 47 (osbind.h) 
Got a disk transfer address 
#include <osbind.h> 
#include <stat.h> 
DMABUFFER *Feetdta() 7 


Fgetdta gets and returns the disk transfer address that had been set by Fsetdt 
and will be used by Fsfirstand Fsnext. 


Example 
The following example creates a version of the find utility for TOS, 
generates a full path name and description for every file in your file system; 


guiput can be piped to if you wish wo Find where you stored a particular file, 
‘oltows: 


find | earep filename 


‘This example demonstrates the TOS functions Fgetdta, Fsetdta, Fsflest, 
Fsnext, It also demonstrates the use of Isascii, isupper, free, malloc, sires 
strepy, strlen, and tolower. q 


‘This example also demonstrates how to use the global variable _stksize to ch 
For stack overflow. 


Wineuse <oabind.h> 
Winetude <stot.h> 

Ainelude <etype. 
extern long ste 


7* Translate string to Lover case */ 
char *lowerease(naed 
char Yane; 
« 
register char *p = nane; register Int ¢; 


Maile (c= *p) "pre = Ibascti(c) RE isuppere) ? toloverted + 


> 


71 Concatentate path suffix to path prefix */ 
char *dircat(pte, sfx) 

register char pfs, “ef 
« 


extern char tealloct), *streatt; 
register cher *p; register int rb, rpfx: 
nb = (pfx = strlen(pfx)) + 1 + strlen(stay + 1; 
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tt cop = mattoccrb): 
strepy(p, pind: 

fF (rpix |= 0 Bk ptxtnptent 
return streattp, $f; 


0 extend; 


= NID strean(p, “WV 


Fy 


[= Search the directory specified by chane */ 
findrame) 
char "rane; 
« 
register char *globnane, *newmane; OMABUFFER dumb, “saved; 
iF (Clongytsaved < _stkefzert2) € 
printf(™stack near overflow in finde)\n\e"; return; 
y 
Globnane = dreat(nane, 949; 
‘saved = COMBUFFER *)Faetdta(); 
Feetdtacdanb); 


[¥ (retiretgtebname, OnE wr 9) © 
oe « 
\f (Gib. frome tt) t= 4.4) ¢ 
rewiane = ircat(nome, dumb. fname 
printf (oxen, 
Find(newnane) 
tree(newase); 


> 


Y vile (Fonexte) == 005 
> 

Yrew(olobrane); 
Faetdtatsaved); 


> 


ing 
G 
fineiouy; return 0; 
y 
See Also 
Fsetdta, Fsflest, Fsnext, gemdos, TOS 


{gets—STDIO function (libe.a/fgets) 
Read line from stream 
#include <stdio.h> 
char *fgets(s, n, fp) char *s; Int rj FILE */p; 


fgets reads characters from the stream /p into string s until 1 characters have 
been read or until a newline or EOF is encountered. It retains the newline, if 
any, and appends e NUL character at the end of of the string. fgets returns the 
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argument s if any characters were read, and NULL if none were read. 


Example 
‘This example looks for the pattern pattern given by argv{1] in standard input 
in file argv{2]. Tt demonstrates the functions pnmatch, fgets, and freopen, 


Hinetude <stdio.h> 
define WAXLINE 128 
char buf [MAXLINE); 


maintaroe, srav) int acces char *aravtl; € 


{f carge t= 2 68 arge {= 3) 
fotalrusage: prmetch pattern { file 1%); 
if Carge == 3 AE treopentargvi2i, "rm", stdin) == MULL) 


fatal(tearnot open input file"); 
while Claetstbut, MAXLINE, stdin) t= MULLD ¢ 
if (prmatch(buf, argvitt, 19) 


fatal(nread errer*); 
exit(095 
> 
fatalcs) char 87 ( 
fprinet(atderr, "prmatch: Zain", 9); 
exits 
> 
See Also 
STDIO 
The C Programming Language, page 155 
Diagnostics 


fgets returns NULL if an error occurs, or if EOF is seen before any charact 
are read, 


fgetw—STDIO function (libe.a/getw) 
Rend integer from stream 
#include <stdio.h> 
int fgetw(/p) FILE */p; 


fgetw is a function that reads an integer from the stream fp. 


See Also 
STDIO 
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Notes 
fgetw returns the value EOF on errors. A call to feof or ferror may be neces- 
sary to distinguish this value from a valid word, 


field—Definition, 
A field is an area that is set apart from whatever surrounds it, and that is 
defined as containing a particular type of data. In the context of C progra: 
ming, a field is either an element of a structure, or a set of adjacent bits within 
an int, 
See Also 
bit map, data formats, structure 
The C Programming Language, page 136 


file—Command 
‘Name a file's type 
file file 


file names the type of each file named, It examines files to make an educated 
guess about their format. 


file recognizes the following classes of text files; files of commands to the shell; 
files containing the source for a C program; files containing assembly language 
source; files containing unformatted documents that can be passed to nroff, and 
plain text files that fit into none of the above categories. 


file recognizes the following classes of non-text or binary data files: the various 
forms of archives, object files, and link modules for various machines, and mis- 
cellaneous binary data files. 


See Also 
commands, Is, msh, size 


Notes 
Because file only reads a set amount of data to determine the class of a text file, 
mistakes can happen, 


file—Definition 
A file is a mass of bits that has been given a name and is stored on a nonvolatile 
medium. These bits may be ASCII characters or machine-readable material of 
some sort. Under the UNIX system, the COHERENT system, and related 
operating systems, external devices can mimic files, in that they can be opened, 
closed, read, and written to in a manner identical to that of files. 
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FILE—Definition 


file descriptor—Definition 


fileno—STDIO function (Itbe.a/fileno) 


fle 


See Also 
close, fopen, felose, FILE, open 


Descriptor for a file stream 
include <stdio.h> ( 


FILE describes a stream or a peripheral device through which data flow. It 
defined in the header file stdio.h. A pointer to FILE is returned by fone 
freopen, and related functions. 

See Also 

fopen, freopen, stdio.h, stream 


A file descriptor is an integer that appears as an entry in a table of files, Le 
used by routines like open, close, and Iseek to work with files. Note that a 
descriptor is rol the same as a file pointer, which is used by routines like fop 

felose, or fread. Note, too, that TOS routines use the term handle as a synonyi 
for “file descriptor”. 


Get file descriptor 

#include <stdio.h> 

Fileno(/p) FILE */p5 

fileno returns the file descriptor, a small, non-negative integer, associated 
the stream fp. This file descriptor, called the handle, is the integer returned b3 
the open or creat call, which a routine such as fopen used to create the stream 
See Also 

STDIO 


je arrays—Definition 

Flexible arrays are arrays whose length is not declared explicitly, Each has 
actly one empty ‘{J' array bound declaration, and if the array is multidimet 
sional, then the flexible dimension of the array must be the first array bound i 
the declaration. 


Flexible arrays occur in only a few contexts; for example, as parameters; 


cher *eravil: 
her pt [8); 
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aS extern declarations: 
extern Int endl; 

as extern or static initialized definitions: 
static chor digit ()=01Zsi567"; 

or asa member of a structure, usually, though not necessarily, the last: 
struct nlist ¢ 


char name! 


” 
See Also 
array, data types 


Float—Definition 

Toating point numbers are a subset of the real numbers. Each has a built: 
fadix point that shifts, or “floats, as the value of the number changes. It con- 
Fists of one sign bit, which indicates whether the number is positive or negative; 
bits that encode the number's exponent; and bits that encode the number's frac 
fiom, of the number upon which the exponent works. Note that elsewhere, the 
(artijon is often called the mantissa. In general, the magnitude of the number 
tnooded depends upon the number of bits in the exponent, whereas its precision 
depends upon the number of bits in the fraction. 


The exponent often uses a bias, This is a value that is subtracted from the ex- 
ponent to yield the power of two by which the fraction will be increased, 
Floating point numbers come in two levels of precision: single precision, called 
floats; and double precision, called doubles. With most microprocessors, 
Siseof{float) returns four, which indicates that it is four chars (bytes) long; and 
sizeof(double) returns eight. 


Several formats are used 10 encode floats, including IEEE, DECVAX, and BCD 
(binary coded decimal), Mark Williams C uses DECVAX format, Each formar 
is described below. 
DECVAX Format 
The 32 bits in a float consist of one sign bit, an eight-bit exponent, and a 23- 
bit fraction, as follows: 

Sign Exponent Frestion 

Ja ceceeneje _ftfteet | errenrte)fesrertfl 

sys ayteS Byte? Byte 

Note that the exponent has a bias of 12 


If the sign bit is set 10 one, the number is negative; if itis set to zero, then the 
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‘number is positive, If the number is all zeroes, then it equals zer 
and fraction of zero plus a sign of one (““negative zero”) is by defi 
number. All other forms are numeric values, 


‘The format for doubles simply adds another 32 fraction bits to the end of th 
float representation, as follows: 


Sign Exponent Mantisss 
[a exoccce |e #ffr4e] ft fFFt te | Feet e44s | EFF EEEE | FFF ETE ET] PFET EEE | FEE FETERL 

byteS byte? Byte S Bytes Byte 4 Byte 3 Byte? Byte t 
For this reason, a double under Mark Williams C has double the precision of 
float, but the same niagnitude. 


TEEE Format 
‘The TEEE encoding of a float is the same as that in the DECVAX for 
Note, however, that the exponent has a bias of 127, rather than 129. 


Unlike the DECVAX format, IEEE format assigns special values to 9 numbeb 
of floating point numbers, Note that in the following description, a tiny e 
ponent is one that is all zeroes, and a Auge exponent is one that is all ones: 


* A tiny exponent with a fraction of zero equals zero, regardless of the sat 
ting of the sign bit. 

‘A huge exponent with a fraction of zero equals infinity, regardless of 
setting of the sign bit, 
‘A tiny exponent with a fraction greater than zero is a denormatized num 
ber, ive,, a number that is less than the least normalized number. 

‘A huge exponent with a fraction greater than zero is, by definition, not @ 
number. These values can be used to handle special conditions. 


‘The 64 bits in a double unlike the IEEE format, does not increase the num! 
of exponent bits, but consist of a sign bit, an 11-bit exponent, and a 5: 
fraction, as follows: 


Sign Exponent Kontissa 
[5 _ceceecelecce ff Ft] Ff ttt tts | FFtieete | FFT reTPe | Freer eEE | FFE | FIFE FTE] 
syte 8 Bric 7 fyte S ByieS Syte Byte 3 Byte? uyte t 


Note that the exponent has a bias of 1,02: 
as for floats. 


BCD Format 

The BCD (“binary coded decimal”) format is used in accounting, to elimina 
rounding errors that alter the worth of an account by a fraction of a cent. 
that reason, BCD format consists of 2 sign (s), an exponent (e), and a chain. 
ffor-bir amber cach of which is defined to hold the digits zero through nin 


A BCD float has a sign bit, seven bits of exponent, and six four-bit deci 


The rules of encoding are the 
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numbers, as follows: 
Sign Exponent Mantissa 
|r eeeeeee| cide decd | ees aafdace cd] 
Byte Byte3 Byte? Byte t 
A BCD double has a sign bit, 11 bits of exponent, and 13 four-bit decimal 
numbers, as follows: 


Sign Exponent Mantissa 
Js eoceeee|ecee dd] ceded il dad ddd acd id eid cd 
ayteB Byte? ayteo Bytes Bytes Bye 3 Bytez Byte 


Note that passing the hexadecimal numbers A through F in a decimal digit 
yields unpredictable results. 


Note the Following rules in handling BCD numbers: 


* A tiny exponent with a fraction of zero equals zero. 

* A tiny exponent with a fraction of non-zero indicates a denormalized 

+ A-huge exponent with a fraction of zero indicates infinity, 

* A huge exponent with a fraction of non-zero is, by definition, not a 
number; these non-numbers are used to indicate errors. 

See Also 


dats formats, declarations, double 
The Art of Computer Programming, vol.2, page 180// 


floor-—Mathematics function (Iibm.a/floor) 
Set a numeric floor 
include <math.h> 
double floor(=) double 


floor sets 2 numeric floor. It returns a double-precision floating point number 
whose value is the largest integer less than or equal to 
Example 

For an example of this function, see the entry for cell. 
See Also 

abs, ceil, fabs, frexp, mathematics library 


Flopfmt—xbios function 10 (osbind.h) 
Format tracks on a floppy disk 
#include <osbind.h> 
#include <xbios.h> 
int Flopfmt(buffer. filler, device sectors, track, side, interleave, magic, new) 
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char *buffer, *filler. *magic; int device, sectors, track, side, interleave, news 


Flopfmt formats a track on a floppy disk. The Atari SF314 and SF354 flop 
disk drives each support 80 tracks per disk, and zero to ten sectors per track. 


buffer points toa buffer large enough to hold the image of an entire track 
{filler is unused, and can be set to anything. device is the number of the floppy 
disk drive, i.e., zero or one. sectors is the number of sectors to format 
track; the usual number is nine. track is the number of the track that you 

to format, from zero to 79. side is the side of the floppy disk on which 
wish to write, ie, zero or one. interleave is the number that governs the inter= 
leaving of sectors; it is usually set to one, magic is a magic number that must be 
set to 0x87654321, 


Finally, new is the word-fill value that is used for new sectors; a good setting ig 
OXESES. 


Flopfmt returns zero if the information was written correctly, and returns | 
numeric error code if it was not. If bad sectors are discovered, their numb 
are written into huffer in the form of a NUL-terminated string. ‘The user th 
has the choice of attempting to re-format the sector, or recording this string. 
map out bad sectors in any further attempts to write to that track, 


Example 
‘This example formats a single-sided floppy disk and it 
tracks, It demonstrates the macros Flopfmt, Flopwr, and Protobt, 


Winelude <stdio.h> 
fineluse <oubied.h> 
‘def ine BLANK (OKESES) Standard sector format value */ 


” 
Hidetine MAGIC COXBTES4B21L) ———7* Kanditory magic runber value */ 
sof je BUFSIZE (941024) 77 Butter size for 9 sectors */ 


extern Int errno; 1" Ervor number for perrort) */ 
maine) € 

nt treck; /* Track counter */ 

int sider /* Sige counter */ 

int status: 7% Stetus word... */ 

short "bt; 7* Butter pre. 


1 Reply..= */ 

77 Pointer for bed block dump */ 

side = 0; /* Only format side 0 */ 

princf(*Really forsat disk in drive 87 "7 

Flush¢stdout); 

FF (reply = Crawcingy) t= ty! Bb reply t= "Y9) ¢ 
Printt(No. Floppy in drive 8 not formatted. \r); 

ere0005 
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printfceves\n): 
prinefuPress any key shen ready. 
fflushstdout); 

Craweing; 
printfnn) 
bf = (short 


) mal Loc ¢BUFSIZED; 


[> First -- Format the floppy */ 

for (track=0; trackeB0; tracke+) ¢ 
printf Cinow formatting tract %d:", track); 
#fluah¢stdeut): 
status © Floptnt(bf, OL, 1, 9, track, side, 1, mate 


iF (status) ¢ 
‘siddle = of: 
prinefo*ven\ne, status); 
waite (omiadien ¢ 
rint#("\tBed sector Xa\n", middlese; 
> 
> else ( 
printte\cokay\n"y 
> 
> 


printtc*Format of all tracks completed\n'); 
Brinet(*Any key to continue. 8); 

#flushcstdout); 

Crawetnz 

printt(Hinitlal (zing directory structure\nt); 

r 

Now, clear aut the first tvo tracks (all zero8... 
+ Firat, zero out the buffer. 


5 track < (BUFSIZED1); bf erackes} = 0}; 


7 Now, write (t to all sectors of the frat two tracks */ 
for (tracked;track<2;) ¢ 
print?(M2eroing track %d.\n", track 
Ve tstatus = Flopwrcbf, OL, 4, 1, tracker, 0, 9) € 
‘errno = “status: 
perrort*Flopwr failure): 


> 


[7 Now, we will prototype the boot Bleck... */ 
Protobttht, (Long)Randon(), 2, 09; 
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(7 Finally, write this out to the Boor sector, 
tus = Floper(bt, Ob, 1, 1, 8, 8, 197 
Hf (status) € 

errno = -stotus: 

perror(turite of boot-block fafled."); 


> 


[7 Verity the write... */ 
‘status = FloprercbF, OL, 1, 1, 9,0, 195 
ff (status) € 

‘errno = ~status; 

perrar(mverify of boot-block failed.*); 


> 


printf(*Progeam done. Dis 
FreetbF); 
Prerm¢); 


acive 


formatted. \nt); 


> 


See Also 
TOS, xbios 


Read sectors on a floppy 
‘#include <osblad.h> 
iinclude <xbios.h> 

Int Floprd(huffer. filler. device. sector, track, side, count) 
char *huffer. *filior; int device, sector. track. side, counts 


Floprd reads one or more sectors on a floppy disk. filler is not used, but m 
be passed properly for this function to work. buffer must point to a buffer that 
is large enough to hold the number of sectors read. device ig the number of the 
device, ie., zero or one. sector is the sector at which to begin reading, ie., one 
through nine. track is the track number to seek to, i.e., zero through 79. side ig 
the side of the floppy to read, zero or one. Finally, count is the number of see= 
tors to read; this can be no greater than the number of sectors on the track. 


Floprd returns zero if the read succeeded, and returns an error code number if 
it did not, 


Example 


Finelude <osbind.h> 
inelude <bios.h> 

gefine uwordcx) —(Cunsignedd(x) 

define Ulong(x) —(Cunsigned Long)(30) 
define cand(x.¥)  Cuwwerdtxd | Cumordty3<<8)) 
det ine cand(x,y,2) (esneta,y)| (ulongt2)<<16)) 


isk 


Lexicon Flopver 


erruct bp ty 
maine) C 
Floprdtsbb, OL, 1, 1, 0, 9, 1 
printf(userial runber: 2u\n", 
‘can(bb.tp_eerial (0) ,B.bp serial (11 bb.bo serial (219); 


printf(tbytes per cectors Mu\n", 
‘cant bb.bp_bps (0) ,bb.bp_bpst13)3; 
printttsectors per cluster: Ba\n", 
‘usord¢bb. bp spe): 


(* raed the boot block */ 


printt(Hreserved sectors: 2u\n", 
‘eore(bb.b_res{0),bb.bp_resi1}); 
printt(inunber of fate: Mu\nt, 
‘uvord( te. bp nfate)); 
printt(*root directory entries %\n*, 
cero bb.bp_ndi rs (01 ,bb.bp_ndirstt} 99; 
printfo"sectors on media: Ru\nt 
‘card (bb,.bp_nsects {0} ,bb-tp_nenctst1}))2 


printtctmedia deseriptars Main, 
‘wword(bb.bp_nedie)) 

peintt(Msectors per fat: Mant, 
ceard(bb.bp_ spf (0) ,bb. bp spf1939); 

printf(vsectors par track: %u\nt, 
‘eand(bb,tp, spt (0) ,Bb.bp spe11199; 


printt(*heods per devices an, 
‘cond(bb,bp_neldes (01 ,.bp_natdes 129; 
print higden teeters: %\n, 
‘cen2(Bb.bp_rh¥0(0) ,25-bp_en\at1299; 
print*(#check suai Xx\n",,canz(bb.bp_ehkf0) ,bo.bp chk (12395 
return 0; 


) 


See Also 
Flopwr, TOS, xblos 


Flopver—xblos function 19 (osbind.h) 
Verify a floppy disk 
#include <osbind.t> 
+#include <xbios.h> 
int Flopver(buffer, filler, device, sector, track, side, count) 
char *huffer. *Jiller; int device, sector, track, side, count 


Flopver reads @ sector from a floppy disk, to verify that it can in fact be read. 
buffer points to @ buffer of 1,024 bytes into which a list of bad sectors (if any) 
will be written, filler is not used, aad can be initialized ta anything. device is 
the number of the floppy disk, and can be set to zero or one. sector is the num- 
ber of the sector to read, one through nine. track is the track on which to seek 
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the sector in question, zero through 19. side is the side of the disk to read, 
or one. Finally, count is the number of sectors to read, and can be no great 
than the number of sectors available on a track. 


Flopyer returns zero if it could read the sector, and returns an error code if it 
could not. If it found bad sectors, it writes a NUL-terminated string of the 
numbers of those sectors into buffer; otherwise, it writes zero into buffer. 


Example 
For an example of how to use this macro, see the entry for Flopfmt. 


See Also 
Flopfmt, Floprd, Flopwr, TOS, xbios 


Flopwr—xbios function 9 (osbind.h) 
Write sectors on a floppy disk 
#include <osbind.h> 
Hinclude <xbios.t> 

int Flopwe(bu/fer. filler, device, sector, track, side, count) 
char *buffer, *filler; int device, sector, track, side. count; 


Flopwr writes one or more sectors on a floppy disk. filler is not used, but must 
be passed properly for this function to work, buffer points to a buffer that 
holds the information to written onto the disk. device is the number of the 
device, ie., zero or one. sector is the sector at which to begin writing, ie., one 
through nine. track is the track number to seek to, i.e, zero through 79. side 
the side of the floppy on which to write, zero or one, Finally, coun! is the 
number of sectors t0 write; this can be no greater than the number of sectors On 
the track, 


Flopwr returns zero if it succeeded in writing the information, and return 
error code number if it did not. Note that writing over the boot sector on the 
disk (sector 1, side 0, track 0) is not recommended. 


Example 
For an example of how to use this macro, see the entry for Flopfmt, 
‘See Also 

Floprd, TOS, xbios 


fopen—STDIO function (libe.a/fopen) 

Open a stream for standard 1/O 
#include <stdio.h> 
FILE *fopen (name. type) char *name, *typet 
fopen allocates and initializes a FILE structure, of stream; opens or creates 
file name; and returns @ pointer to the structure for use by other STDIO 
routines. name may refer either toa real file or to ane of the devices aux:, com 


220 Mark Williams: 


‘Lexicon fopen 


or prn:. :ype is a string that consists of one or more of the characters “rwab", to 
indicate the mode of the string, as follows: 


fread ASCII; error if file not found 

rb read binary data 

w write ASCII; truncate if found, create 
if not found 

wb write binary data 

@ append ASCII; no truncation, create 

not found 

ab append binary data 

rw read and write ASCH; no truncation, 
error if not found 

rwb read and write binary data 

wr write and read ASCII; truncate if 
found, create if not found 

wrb write and read binary data 

ar append and read ASCII; no truncation, 
cteate if not found 

arb append and read binary data 


r+, w+, and a+ are synonyms for rw, wr, and ar, respectively. The modes that 
contain a set the seek pointer to point at the end of the file, so that data may be 
appended; all other modes set it to point at the beginning of the file. 


Example 
This example copies argvl1} to argvi2] using stdio routines. It demonstrates the 
functions fopen, fread, write, fclose, and feof, 


Hinctude <stdio.h» 
‘char buf [OUFSIZ}; 


av) int argc; cher *argvil; ( 
eer FILE Fi, 


if (argc 143) 
fatal (WUsage: copy source dest ination"); 
it Cer fp = fopentarsvctly "rbH)) == MULL) 
Feral (cannot open Input t1LeH); 
if (ofp = fopentacgvi2i, "6")) == WULL) 
Fatal lesnoat open output #1Le); 
while Con = freadtbuf, 1, BUFSIZ, ifp)) 12 0) € 
if (furitetbut, 1, n, ofp) T= 
fatal (nirite error); 
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form_: 
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HF C1Feotcifen) 
fatal reed errors); 
if (felosecitp) == EOF || felosecotp) = EOF) 
fatalcicennot close"); 
onree005 
> 


fatale) cher #5; C 
eflstderr, Meopy: Ke\n*, 3): 


See Also 
FILE, freopen, STDIO 
‘The C Programming Language, page 151, 167 


Diagnostics 

fopen returns NULL or if it cannot allocate a FILE structure, if the (pe 
ig nonsense, or if the call to open or creat fails. Currently, only 20 FILE. 
tures can be allocated per program, including stdin, stdout, and stderr. 


Open a file 
include <osbind-h> 
Jong Fopen(name, mode) char *name; int mode; 


Fopen opens a file, name points to the file’s path name, which must be a NUL= 
terminated string, mode is an integer than encodes the mode in which the file 
opened, as follows: zero, read only; one, write only; and two, read or writ 
Fopen returns a file handle, which is understood by TOS. 

Example 

For examples of how to use this macro, see the entries for Fseek and Fereate: 


See Also 
gemdos, TOS 


lert—AES function (libaes.a/form_alert) 

Display an alert box 

#include <aesbind.h> 

int form_alert(button, string) int button; char *strings 


form_alert is an AES routine that displays an alest dialogue box on the sore 
‘An alert dialogue box consists of three elements: an icon, which is selected from 
4a predefined set of three; text, which describes the alert; and one or more“ 
buttons", of little boxes that the user clicks to indicate what he wants to da. 


button defines which exit button is the default; the default button is drawn with 
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a heavier outline and it is the one selected if the user presses the return key in- 
stead of using the mouse. The default is set as follows: zero, no default butto 
one, first exit button; two, second exit button; and three, third exit button. 
string points to the string used with the alert box. The string has the following 
format: 


im text texity 


The square brackets are entered literally, m refers to the number of the icon 
you wish to display, as follows; 


0 no icon 

1 NOTE icon (exclamation point) 
2 WAIT icon (question mark) 
3 


STOP icon (stop sign) 


text is the text displayed within the alert box. Note that an alert box can hold 
no more than five lines of text, each no longer than 40 characters, A vertical 
bar ‘|’ indicates a line break, exit describes the exit buttons. It can have no 
more than 20 characters. If you want more than one exit button, separate their 
texts with a vertical bar, For example, 


[B1Connot find #ile[Do you wish to try again?) fault |Try againt 


indicates that you want the STOP icon (icon no. 3), that the box is to have two 
lines of text (“Cannot find file/Do you wish to try again?"), and that you want 
two exit buttons, one marked “Quit” and the other marked “Try again", 


form_alert returns the number of the exit button selected. 


Example 

This example shows a program called alert.c; it opens a text file and displays its 
contents, and keeps the tent on the screen until a key is pressed. The program 
‘uses fsel_input to accept information from the user, and form_alert to handle 
various error conditions. Note that the line 


char DIRPATHISO) = "b:\\examples\\*. 


points to the directory examined; you should insert the name of the directory 
you wish to work with. The defavit is a2\, 


Binclude <etypesh> 
Winelude <aesbind.h> 


define CANTOREN & 
fidetine NOTASCIT 1 
fHsefine FOULLP 2 
fHdef ine UNDEFINED 3 
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cer DIRPATHBOD ~ Hbs\\examplea\\t, 
static char “STRING = € 
"123 teannot Open Fite] ouit|Try Agsin", 
“EDEFiLe Ts Not ASCII (OKI, 
"P3) [Foul-up in fsel_ingut a", 
3] [Undefined Error] 0K)" 


Py 


FILE *newopent 
FILE tmp; 
char name (00); 
int button: 
rome tO) = *\0"; 
if (fsel_inputiDIRPATH, name, Sbutton) == 0 
alert(FouLUP); 
alse 
returnttopentnane, "8992 
5 
mained © 
FILE *¥p; 
Int eh; 


sppl_init(o; 

MAILE (Cp ® newopena) =* MULL ¢ 
‘lert(CANTOPEN); 

> 


While (coh * faerectpy) t= EDF) ¢ 


HCE) 
putehar(eh); 
else 
eeNOTASCH 

> 
fevnt_keybdd; ——_/* stop processing until keyboard hit */ 
appl_exitz 
exiXt0); 
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See Also 
‘AES, cc, gem, TOS 


form_center—AFS function (libaes.a/form_center) 
Center an object on the screen 
Ainclude <aesbind.h> 
include <obdefs.h> 
int form_center( picture. location) OBJECT * picture; Prect location; 
form_center is an AES routine that centers an object on the screen. 


picture points to the object being manipulated. The type OBJECT is defined in 
the header file obdefs.h, 

location points to where the object is centered on the screen, It is declared to 
bbe of type Prect, which is defined in the header file aesbind.h. Prect is a struc~ 
ture that consists of four pointers to integers, as follows: 


x X value of centered coordinate 
y _ Y value of centered coordinate 
w width of centered object 
hh height of centered object 


form_center always returns one. 
Example 
For an example of this routine, see the entry for object. 


See Also 
‘AES, abdefs.h, object, TOS 


form_dial—AES function (Iibaes.a/form_dial) 
Reserve/free screen space for dialogue 
#include <aesbind.h> 
int form_dial(flag, smallbox, bighox) int flag; Prect smallbox, bigbox; 
form_dlal is an AES routine that either reserves space for a dialogue box, or 
frees Space previously reserved. flag indicates whether the space is to be 
reserved or freed; zero indicates reserve and three indicates free. The space 
being reserved was originally designed to be a box that grows from smallbox to 
bigbox, as shown by the bindings. 
Both smallbox and bigbox are of type Prect, which is declared in the header file 
aesbind.h, Prect is a structure that consists of four pointers to integers, as 
follows: 
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form_error—AES function (Iibaes.a/form_error) 
“Display a DOS error alert 
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X value of contered coordinat 
Y value of centered coordinate 
width of centered object 
height of centered object 


waun 


form dial returns zero if an error occurred, and a number greater than zero if 
one did not. 

Example 

For an example of this routine, see the entry for object. 
See Also 

AES, form_do, object, TOS 


in (Vibaes.a/form_do) 
Handle user input in form dialogue 
#include <aesbind.h> 

int form_do(éree, ob ject) 

long tree; int object; 


form_do is an AES routine that handles text the user may need to input into 
object. tree points to the object tree that will accept the text, ohject indicat 
the object within the tree that has an editable text field; zero indicates that 
tree contains no editable text field. form_do returns the index of the obj 
that closes the dialogue. 


Example é 
For an example of this routine, see the entry for object. 


See Also 
AES, form_dial, object, TOS 


include <aesbind.h> 
int form_error(error) 
int error; 


form_error is an AES routine that displays a preset DOS error alert. error is! 
integer that indicates which error message you wish to display, as follows 
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Undefined 
Undefined 

Cannot find file or folder 

Same as 2 

No room to open another document 
Tem with this name already exists 
Undefined 

Undefined 

Not enough RAM to run application 
Undefined 

10 Same as 8 

11 Same as 8 

12 Undefined 

13 Undefined 

14 Undefined 

15 Specified drive does not exist 

16 Cannot delete current folder 

17 Undefined 

18 Same as 2 


wemsaneunee 


Note that the above numbers correspond to error codes under MS-DOS. All 
codes greater than 18 are associated with no specific error message. form_error 
returns the number of the exit button that the user clicked, from one through 
three, At present, all error alerts have only one exit button. 


Example 
‘This example displays the preset error forms. 


inetude <aesbing 
mating) ¢ 


apol_init; 
for Ceounter = 0; counter <= 20; counters) 
form errortcownter); 


See Also 
AES, TOS 


fprintf—STDIO function (libe.a/printf) 


Format output 
#include <stdio.h> 
fprintf(/p, format [ , arg ]...) 
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FILE *fp; char * format; 


Sprintf uses the format string to specify an output format for each arg, which it 
then writes into the file fp. See printf for a description of fprintf’s formatting 
codes. 


See Also 

printf, sprintf, STDIO 

The C Programming Language, page 152 

Notes 

Because C does not perform type checking, it is essential that an argument 
match its specification. For example, if the argument is a long and 


specification is for an lat, fprintf will peel off the first word of that long 
present it as an int. 


{pute-STDIO function (libe.a/fpute) 
Write character to stream 
include <stdio.h> 
Ipute(c, /p) char ¢ FILE *fp5 


Spute writes the character ¢ onto file stream fp, and returns ¢ upon success, 


Example 
‘The following example demonstrates fpute. 


fineluse <etdio. he 
naincae 
MLE “fp, 
int 
int infiter2o1; 
ne ouetitetza); 
printf (Enter name to copys"); 
getscinf iter: 
printf("Eneer name of new fi 


geta(ourfiled: 
if (Cfp = fopewinfile,tray) t= MALLY ¢ 
1 (Clout = fopencourtite,we)) t= MULL) 


vile C(ch = foetetp)) 
fputecen, faut) 
else printf(canot write Xs.\nt, outfile); 


OF) 


> 
else peintt(mtanet read Xs.\n", Infiled; 
felose tp); 

felose(fout 
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See Also 
STDIO. 


Diagnostics 
EOF is returned when a write error occurs, ¢.g., when a disk runs out of space. 


fputs—STDIO function (Iibe.a/fputs) 

Write string to stream 

#include <stdio.h> 

{puts(string, fp) char *string; FILE "fp; 


puts writes string onto the stream fp. Unlike its cousin puts, it does not append 
a newline character to the end of string. 

See Also 

STDIO 

The C Programming Language, page 155 


fpatw—STDIO function (libe.a/fputw) 
Write sn integer to a stream 
winclude <stdio.h> 


{putw(word, fp) int word; FILE */p; 

Tputw writes word to the stream /p, and returns the value written. 
See Also 

STDIO 

Diagnostics 


EOF is returned when an error occurs. A call to ferror may be needed to dis- 
tinguish this value from a valid data item. 


fread—STDIO function (libe.a/fread) 

Read data from stream 

include <stdio.h> 

int fread(buffer, size, n, fp) char *buffer; 
unsigned size. FILE */p; 


fread reads n items of size bytes long each, from stream fp into memory loca- 
tion buffer, and returns the number of items read. 


Example 
For an example of how to use this function, see the entry for fopen. 
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{ree—General function (libe.a/malloc) 


See Also 
fwrite, STDIO 


Diagnostics 
fread returns 0 on end of file or error, and the number of items read otherwise. 


Read a file 

#include <osbind.th> 

long Fread(handle, n, buffer) 

int handle; long n; char *buf fer; 

Fread reads n bytes from a file opened by Fopen or Fereate. 


handle is the file handle generated when the file was opened; buffer points to 
the location where the material being read is stored, Fread returns r if the file 
was read successfully, and an error code if it was not, 

Example 

For examples of how to use this macro, see the entries for Fseek and Fereate, 
See Also 

gemdos, TOS 


Return dynamic memory to free memory pool 
free(pir) char "pir; 


free helps to manage a program's arena. It returns to the free memory pool 
memory that had previously been allocated by malloc or calloc. free marks the 
block indicated by fir as unused and coalesces it with contiguous free blocks, 
ptr must have been obtained from malloc, calloc, or realtoc. 

Example 

For an example of how to use this routine, see the entry for malloc, For an ex~ 
‘ample of this function in a TOS application, see the entry for Fgetdta. 

See Also 

arena, calloc, malloc, notmem, realloc, setbuf 


Diagnostics 

free prints a message and calls abort if it discovers that the arena has been cor 
rupted, which most often occurs by storing past the bounds of an allocated 
block. 
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Frename—gemdas function 86 (osbind.h) 
Rename a file 
#include <osbind.h> 
long Frename(n, oldpath, newpath) int m; 
shar *oldpath, newpath, 


Frename renames file. oldpath points to the file’s old path name, and newpath 
to its new path name; both names must be NUL-terminated strings. ewpath 
must not be the name of an existing file. m is reserved for TOS, and must be 
zero. Frename can move a file to another subdirectory, but only on the same 
disk drive, Tt returns zero if the file could be renamed, non-zero if it could 
101. 


Example 
This example renames a 


include <stdio.h> 
finelude <osbind, he 


extern int errno; 77 global for Lost error. 


raincarge, argy) int araes 
nt stax 


Wf (arge <3) ¢ 
Dprintf(*usage: Frenane oldrame newrame\n"); 
Perm); 

> 

Hf ((statursFrename(O, argvit), ergvi2iy) 1 09 ¢ 
errno = ~stetur 
perror("Rename fal led); 
Prenat); 


» 
print{CHFile ts renamed to Xe\n*, argvit], argviZiy; 
Prerm0; 

) 


See Also 
gemdos, TOS 


freopen—STDIO function (libe.a/freopen) 
Open a stream for standard 1/0 
#include <stdio.h> 
FILE *freopen (name, type, fp) 
char *name, “type, FILE */p; 
freopen reinitializes fp, closes the file currently associated with it, opens or 
creates file name, and returns a poister to the structure for use by other STDIO 
routines. name may refer either to a real file or to one of the devices aux:, con:, 
or prt 
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frexp—General function (libe.a/frexp) 


fscanf—STDIO function (Iibe.a/seanf) 
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iype ia string that consists of one or more of the characters “rwab” (for read, 
write, append, binary) to indicate the mode of the stream. For additional dis- 
cussion of the rype variable, see fopen. freopen differs from fopen only in 

fp specifies the stream to be used. Any stream previously associated with fp is 
closed by fclose. freopen is usually used to change the meaning of stdin 
stdout, or stderr. 


Example 
For an example of how to use freopen, see the entry for fgets. 


See Also 
fopen, STDIO 


Diagnostics 
freopen returns NULL if the type string is nonsense or if the file cannot bi 
opened, Currently, only 20 FILE structures can be allocated per program, it 
cluding stdin, stdout, and stderr 


Separate mantissa and exponent 
double frexp(real, ep) double real; int *ep: 


frexp breaks double-precision floating point numbers into mantissa and 
ponent, It returns the mantissa m of its real argument, such that 1/2 <= m <1 
‘or m=0, and stores the binary exponent ¢ in location ep. These numbers sati 
the equation real =m * 2 


See Also 
atof, ceil, fabs, floor, Idexp, modf 


Format input from a file 
‘#include <stdio-h> 
fseanf(/p, format (. arg | 
FILE */p; char *formar; 


fseanf reads the file fp. and uses the string format to specify a format for each 
arg, which must be a pointer. For more information on fscanf’s conversion 
codes, see scant. 


See Also 
STDIO 
The C Programming Language, page 152 
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Notes 

Because C does not perform type checking, it is essential that an argument 
metch its specification. For that reason, fscanf is best used only to process data 
thet you are certain are in the correct data format, such as data previously writ- 
ten out with fprintf, 


/fseek) 


Seek on stream 

include <stdio.h> 

Int fseek(/p. where. how) 
FILE */p; long where; int how; 


fecek changes the location where the next read or write operation will occur in 
stream fp. It handles any effects the seek routine might have had on the internal 
buffering strategies of the system, The arguments where and how specify the 
desired seek position. where indicates the new seek position in the file; it is 
measured from the start of the file if how equals zero, from the current seek 
position if how equals one, and from the end of the file if how equals two. 


Example 
‘This example opens file argel1] and prints its last argv[2] characters (default, 
100). It demonstrates the functions fseek, fell, and fclose, 


binctude <stdto.h> 
extern Long atoll); 
mmaincarge, argv) Int argc: char *argvi 
register FILE Pip; 
register inte; 
ong nehare, sie: 


Wf corge <2 |} ara > 3) 
oral (*Usage: tail file Cnehars 299; 
ehare = (arge #» 3) 7 atel 
TF (Cif = fopentargvit}, re) == HOLL) 
fatal (neannat open input file); 
it (fseekeftp, OL, 2) == -1) [* Seek to end */ 
Fatal onseek erroré: 
size = frell(itpy; /* Find current site */ 
size = (size <nchars) 7 OL 2 size - ochars: 
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if Cfseekcitp, size, 0) 

Fatal (seek error); 

while (Ce = getccitp)) != EOF) 
putchart 

if (felosecite) 

Lteannat clase"); 


FF Seek to point + 


1* copy rest to stdout */ 


) 


fatalcs) char *52 ¢ 
fprintf(stderr, "tai 
exit; 


d 


See Also 
ftell, STDIO 


Diagnostics 
For any diagnostic error, fseek returns -1; otherwise, it returns zero. Note that 
if feeek goes beyond the end of the file, it will not return an error message until 
the corresponding read or write is performed, 


Move a file pointer 
winclude <osbind.h> 
long Fseek(n, handle, mode) long 1; int handle, mode; 


Freck moves a file pointer. handle is the file's handle, which was generated 
when the file was opened; n is a signed long integer that indicates the number 
of bytes the pointer is to be moved. mode contains an integer that encodes the 
manner in Which the pointer is to be moved, as follows. cer, move m bytes. 
from beginning of file; one, move m bytes from current location; and two, move 
n bytes from the end of the file. Fseek returns the number of bytes that the file 
pointer is now located from the beginning of the file. 


Example 
‘This example demonstrates Fseek. It copies one file into another, 


Hinclude <osbind.n> 
include <stat.n> 
Hinelude <errno.h> 
‘char buffer {81923 [8 butter */ 


yoid reversetbutfer, Len) 
char *buffer; int len; 
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watle (fartard ¢ backward) € 
place = *--backward; 
“backward = *forwar 
sforuardts = place: 


ey 


foralcerror, mse) 
int error; char "gz 


« 
perror(meg); 
exit(Vye 

> 


rmaintarge, arav) 
(nt erge; char *argviT 
« 


Int stetus, infd, outfd, size: 
DHABUFFER dan; 


He carve <3) 6 
printf("usege: Faeek source target\n"; 
exitnds 

> 


{f (Cinfd © Fopentaravtt}, 09) € 09 
fatatcinfd, argvitl>; 
Faetdtatkdna); 


Af totatuectatirercargvtt, 265799 1 09 
fatalcetatos, argv]; 
stetus = amd fettr B 7; 


14 (Coutfd = Fereatetaravi2i, status) <0) 
fatal couttd, argvi2}); 
Ma{e (ora. tele > 0) ¢ 
Vf (aaud falze > s{zect butter)? 
size © sizeo! (butter): 


size = cmasd (sire; 


Feeek(cra.d_falze-stze, infd, 00; 

+f ((atarussFrenat inf, Clong)stze, bufter)) < 0) 
FaeleteCargvi2i}, fatal¢stetus, argvitl); 

reverseibutfer, size): 


if Cearatussfurite(outts, (lonedstie, buffer)? < 0) 
Fdeletecargvi2i), faralcscatus, argvi2id; 
ea. fsize “= 128) 
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Fetosecinta; 

Felosetoutfad; 

printf(*File 3 copied to file X6.\n", aravitl, sravi2idy 
return 


3 


See Also 
Fsnext, gemdos, TOS 


Diagnostics 

For any ditgnostic error, Fseek returns -|; otherwise, it returns zero, Note that 
if Fseek goes beyond the end of the file, it will not return an error message un 
Lil the corresponding read or write is performed. 


fsel_input—AES function (libaes.a/fsel_input) 
Select a file 
#include <aesbind.h> 
int fsel_input(directory. file, button) ehar "directory. files int *button; 


fsel_input is an AES routine that allows the user to select @ file in the current 
ectory, or create a new file. It displays a box on the screen; within the box is 
a window that shows the contents of directory. 


‘The user can use the mouse to scroll through the contents of directory and select 
one; she can also move up or down within the directory tree, or specify a new 
directory. The box also contains two “exit buttons”, one marked "Cancel" and 
the other marked "OK", 


directory, as noted above, points to a buffer that holds the name of the direo~ 
tory being read, Note that directory must be large enough to hold the full path 
name for any file selected, including those selected from subdirectories within. 
the directory first displayed. 


To avoid accidentally creating a C-language escape character, be sure to use 
two backslashes *\\" to separate elements of the path name. The default direc- 
tory is named a:\\. The path name must end with a string that indicates which 
files you wish to examine in the directory: for example, “#,*" displays all the: 
files in a directory, whereas “*.c” displays only the C programs. 

If the user clicks # directory while using this function, the name in the buffer 
that directory points to is altered to reflect this change. 


file is the name of the first file in directory. It is initialized by AES. If the user 
selects a file other than the first one in the directory, what file points to is also 
altered to reflect this change. 


button points to s integer that indicates which exit button the user selected: 200 
indicates that she selected the Cancel button, and one indicates that the OK 
button was selected. 
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fsel_input returns zero if an error occurred, and a number greater than 22ro if 
one did not. 


Example 
For an example of this function, see the entry for form_alert 


See Also 
AES, TOS 


Fsetdta—gemdos function 26 (osbind.h) 
Set disk transfer address 
#include <osbind.h> 
include <stat.h> 
void Fsetdta(c) DMABUFFER *c 


Féetdta sets the pointer c to the address of a DMA buffer, a 44-byte buffer that 
can be subsequently used by the macro Fsfiest, It returns nothing, 

Example 

For an example of of this function, see the entry for Fgetdta. 

See Also 

Fgetdta, Fsfirst,gemdos, TOS 


Fsfirst—gemdos function 78 (osbind-h) 
‘Search for first occurrence of a file 
#include <osbind.h> 
winclude <stat.h> 
Tat Estirst(name, arrib) char tnamey tnt attribs 


Feflest searches for the first occurrence of a file name. name points to the file's 
rene, which must be a NUL-terminated string, atirib is an integer that en- 
codes the search's attributes, as follows: 


0x00 normal files only; no hidden files, subdirectories, 
system files, or volume labels will match 

0x01 include read-only files 

x02 include files hidden from directory search 

Ox04 include system files 

0x08 include volume-label files 

Oxt0 include subdirectory 

0520 include files thar have been written to and closed 


Note that if you specify volume label, no other type of file can be searched far. 
Tee cider in which file matches are Found depends on the order in which the 
Giles are arranged in the directory, and is not governed by alphabetical order or 
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creation date. 


If the search is successful, Fsflrst takes the 44-byte DMA buffer that had been 
created with Fsetdta, and ‘ills it as follows: bytes zero through 20, reserved for 
TOS; byte 21, file attributes; bytes 22-23, the file's time stamp; bytes 24-25, the 
file’s date stamp; bytes 26-29, the file's Size: and bytes 30-43, the file's name, 
‘The DMA buffer is declared in the header file stat-h. 

Fsfirst returns E_OK (success) if the search succeeded, and EFILNF (file not 
found) if it did ne 
Example 

For an example of this function, see the entry for Fgetdta. 
See Also 

Fretdta, Fsnext, gemdos, stat-h, TOS 


Fenext—gemdos function 79 (osbind.h) 


‘Search for next occurrence of file name 
#include <osbind.h> 

winclude <stat.h> 

int Fsnext() 


Fsnext continues the search for a file, by using the information that had been 
weitten into the 44-byte file name buffer by Fsfirst or by a previous call to, 
Fsnext. If Fsnext finds another file with the given name, it updates the DMA 
buffer to accommodate the name and attributes of the newly found file, The 
DMA buffer is declared in the header file stat.h. 


Fenext returns E_OK (success) if the search was successful, and ENMFIL (no 


more files) if it was not. 

Example 

For an example of this function see the entry for Fgetdta. 
See Also 


Fofirst, gemdos, stat.h, TOS 


fstat—General function (libe.a/stat) 
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Find file attributes 

‘#include <stat-h> 

{stat(descriptor, staiptr) FILE "descriptor; struct stat *starptr; 

{stat returns a structure that contains the attributes of a file. descriptor points 


to the file descriptor, as returned by the library function fopen, and statptr 
points to a structure of the type stat, is defined in the header file stat.h, 


‘The following summarizes the structure stat and defines the permission and file 
type 


Mark Williams C 


Lexicon ftell-function 


struct etst € 
dev t st dev; 
intat st ines 
Unsigned short et modes 
short st nlinks 
short st_uid; 
short st_gid; 
dev_t strdev; 
size t st size; 
tine t st atime; 
time_t st ntime: 
tine _t st_ctine 


% 

Ade ie $14RON O10) /* 

fidefine S_1INID O02 /* 

féetine S1ISYS 0x04 /* System, hidden fram search */ 
fief ine S1AVOL 0x08 /* Volume Label in firat 11 bytes */ 
dot ine SUIJOIR OXI /* Directory */ 

fetine #_LIWAE 0120 /* Written to and closed */ 


The majority of entries in the structure stat are there to preserve compatibility 
with the COHERENT operating system. Most return meaningless values when 
Used on the Atari ST, with the following exceptions: st_atime, st_mtime, and 
St_ctime all return the time that the file or directory was Tast modified 


See Also 
1s, msh, open, stat, stat.h 


Diagnostics 
{stat returns -1 if the file is not found or if statptr is invalid. 


ftell-STDIO function (libe.a/ftell) 
Return current position of file pointer 
include <stdio.h> 
tong ftell(/p) FILE */p: 
ftell returns the curfent position of the seek pointer. Like its cousin fseek, ftell 
takes into account any buffering that is associated with the stream / 


Example 
For an example of how to use this function, see the entry for fseek. 


See Also 
fseek, STDIO 
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function—Definition 


fwrite-STDIO function (libe.a/fwrite) 


Fwrite—gemdos function 64 (osbind.h) 
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‘A function is the C term for a portion of code that is named, can be invoked by 
name, and that performs a task. Many functions can accept data in the form of 
arguments, modify the data, and return a value to the statement that invoked: 


Although functions most often are described as though they were nouns 
programmers would do well to think of them verbs, for a function's name is 
predicate of almost every C statement. 


See Also 
data types, portability 


Write to stream 
#include <stdio.h> 

int fwelte( buffer, size, n. fp) 
char *huffer; unsigned size. n; FILE */p; 4 


fwrlte writes m items of size bytes each from bu/fer to stream fp, and retute 


the number of items written. 


Example 
For an example of how to use this function, see the entry for fopen, 


See Also 
fread, STDIO 


Diagnostics 
fwelte normally returns the number of items written; if an error oceurs, 
returned value will not be the same as 71. 


Write into a file 

#include <osbind-h> 

long Fwelte(handle, n, buffer) int handle; long m; char *buffer; 
Fwrlte writes bytes into a file, Aund(e is the file handle that was generated 
when the file was opened by Fopen or Fereate. buffer points to the material 
be written. Fwrite returns » if the material was written successfully, and an 
ror code if it was aot. 


Example 
For examples of how to use this macro, see the entries for Fseek and Fereate. 


See Also 
gemdos, TOS 
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gevt—General function (libe.a/gevt) 
Convert floating point numbers to ASC strings 
char *gevt(d, w, buffer) 
double d; int w; char *buffer: 


gevt converts floating point numbers to ASCII strings. It converts its argument 
@ into a string of numerals that is w characters wide and terminated with NUL... 
Unlike its cousins ecvt and fevt, gevt uses a fuffer that is defined by the caller. 
puffer must be large enough to hold the result. When generating its output, 
gevt will mimic fert if possible; otherwise, it mimics ecvt. gevt returns hu/fer. 


See Also 
cevt, fevt, frexp, Idexp, modf, printf 


gem—Command 
Run a GEM-DOS program 
gem command args 


gem allows you to run a GEM-DOS command under the micro-shell msh, It 
resets file handle 2 to the aux: device, Unlike its cousin, the tos command, gem 
enables the mouse cursor 


Note that gem does nor read the environment, you must specify exactly where 
the program is located, and give its full name. 


Because some GEM programs read resource files and expect to find them in the 
current directory, you should use gem with a cd command, For example, 

set gonected c:\games; gem sine.ersi ed! 
allows you to run the GEM applicetion game.prg by typing Sgame. When you 
exit from game, you will be returned to your HOME directory. 
When you are finished, just exit from the GEM-DOS program in the normal 
way, and gem will return you to msh, 


See Also 
‘commands, msh 


Notes 

Some Atari GEM programs appear to depend on the GEM desktop to perform 
unspecified clean-up after they run, and thus cannot be run through the gem 
command. These programs include Atari Logo and Atari BASIC. Running 
these programs under msh may damage memory-resident programs, such as 
RAM disks. 
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gemdefs.h—Header file 
"GEM structures and definitions \ 
include <gemdefs.h> 


gemdefs.h is a header file that declares structures and definitions useful for 
programming in the GEM environment, Many of the mnemonics used through — 
GEM programs are also defined in this file. 


See Also 
AES, header file, TOS, VDI 


gemdos—TOS function 
Call a routine from GEM-DOS 
#include <osbind.h> 
extern long gemdos(1, arg/...argn); 


gemdos allows you to call a GEM-DOS routine directly from your program. 1 
is the number of the routine, and arg! through argn are the argument numbers 
to be used with the routine. In most circumstances, it is unnecessary to use 
gemdos directly, for a library of functions that use it are defined in the header 


file osbind.h. 

The following functions use gemdos: 
Cauxin Read character from serial port 
Cauxis Return serial port input status 
Cauxos Return serial port output status 
Cauxout Write character to serial port 
Cconin Read character from console 
Ceonis Return console input status 7 
Ceonout Write character to console | 
Cconos Return console output status 
Ceonrs Read and edit string from console 
Coonws Write a string to the console 
Cnecin Read character from console, 20 echo 
Cprnos Check parallel port output status 
Cprnout Write character to parallel port 
Crawin Read raw character from console 
Crawio Perform raw 1/O with console 
Dereate Create a subdirectory 
Delete Remove a subdirectory 
Dfree Find free space on disk 
Deetdry Return current disk drive 
Dgetpath Return current directory 
Dsetdry Set the default drive 
Deetpath Set the current directory 
Fattrib Get/set file attributes 
Felose Close file 
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Fereate Create a file 
Fdatime Get/set file's date stamp 
Féelete Delete a file 
Faup Duplicate a file's handle 
Fforee Force a file handle 
Feetdta Get a disk transfer address 
Fopen Open a file 
Fread Read a file 
Frename Rename a file 
Frock Move 2 file pointer 
Fsetdta Set disk transfer address 
Esfirst Search for first occurrence of file 
Fsnext Search for next occurrence of file 
Fwrite Write into a file 
Malloc Allocate dynamic memory 
Mfree Free dynamic memory 
Mshrink Shrink amount of allocated memory 
Pexec Load or execute @ process 
Peerm Terminate a process 
Peermd Terminate a TOS process 
Ptermres Terminate a process but keep in memory 
Tretdate Get date 
Teettime Get time 
Tsetdate Set date 
‘Tsettime Set time 
Syersion Get TOS version number 
See Also 
osbind.h, TOS 


Notes 
No gemdos function will support a recursive call. Attempting to use a recursive 
call with a gemdos function will crash the system, 


Note that all gemdos functions are unbuffered. Combining them with buffered 
1/O routines, such as those in the STDIO library, will lead at best to unpredict~ 
able results. 


gemout.h—Header file 
GEM-DOS file formats and magic numbers 
#include <gemout.h> 


gemout.h is a header file that declares formats for the GEM-DOS executable 
files and archives, It also includes a number of “magic numbers” used in hand- 
ling these formats. 
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See Also 
header file, TOS 


Getbpl—bios function 7 (osbind.h) 
Get pointer to BIOS parameter block for a disk drive 
+#include <osbind.> 
#include <bios-h> 
char *Gethpb(device); 
int device; 


Getbpb returns a pointer to the BIOS parameter block for a given disk drive. 
device is-an integer that indicates which drive you wish to examine: zero, drive” 

ne, drive B; etc. If the BIOS parameter block cannot be determined for 
whatever reason, Getbpb returns zero. 


Example 


The following example dumps the BIOS parameter block for the disk in drive 
i, 


Hinetude <osbind.hr 
Hnetisde <blos.h> 


maine? € 
Struct tp bp; 
bp = (struct bpp *) GetbpbO9; 
print#(*O\sk in drive B:\n"; 
printf(*\tSector Size:\tX5d bytes\n", bp->bp_recs!2); 
printf(\tcluster Size:\t85d bytes (id sectors)\n", 

bp-rtp.claizh, beste elsind; 

printf(\tDirsctory:\thSd sectorsint, bp->bp_ralen) 
Print C\tFAT:\t\PSd aectors\n", Bp! >be 18177 
printfcm\cdate Clusters:\rX5a\n", bp->bp_ruel; 
prinetco\tFlaga:\t\e Malo", tp->be flags); 


y 


See Also 
bios, TOS, 


gele-STDIO macro (stdio.b) 
Read character from stream 
#include <stdio.h> 
int gete(/p) FILE */ps 


gete is a macro that reads 2 character from the stream /p, and returns an int, 
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See Also 
fgetc, getchar, STDIO 
The C Programming Language, page 152 


Diagnostics 
gete returns EOF at end of file or on read error. 


Notes 

Because gete is a macro, arguments with side effects probably will not work as 
expected. Also, gete is 2 complex macro, and its use in expressions of too great 
a complexity may cause unforeseen difficulties. Use of the function fgete may 
solve such a problem. 


getchar-STDIO macro (stdio.h) 
Read character from stream 
winclude <stdio.h> 
int getchar() 


getchar is a macro that reads a character from the standard input. It is equiv- 
alent to gete(stdin). 


See Also 
gete, STDIO 
The C Programming Language, page 144, 152 


Diagnostics 
getchar returns EOF at end of file or on read error. 


yetcol—Command 
Get a color value 
geteol position 


getcol is a command that uses the xbios function Setcolor to read the color for a 
position on the current color palette. position is the palette position in question, 
from zero through 15. 


See Also 
‘commands, seteolor, Setcolor, TOS 


geteny—General function (libe.a/geteny) 
Get environmental variable 
char *getenv(variahle) char ‘variable; 


‘A program may read certain variables in its environment. This allows the 
program to accept information that is specific to you. The environment consists 
of an array of strings, each having the form VAR/ABLE-V ALUE, When called 
with the string VARIABLE, geteny returns a pointer to the string VALUE. 
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See Also 
cc, environment, msh 


Diagnostics 
When VARIABLE is not found or has no value, geteny returns NULL. 


Getmpb—bios function 0 (osbind.h) 
‘Copy memory parameter block 
#inchude <osbind.h> 
include <bios.h> 
vold Getmpb( pointer); 
char *pointer; 


Getmpb tells TOS to copy its memory parameter block into the 24-byte space 
pointed to by pointer, The useful portions of the memory parameter block are 
described in the example; as of this writing, the memory parameter block does 
not appear to be utilized by TOS. Note, too, that the lists returned are in sys~ 
tem-protected memory; unless the user is in supervisor mode, accessing these 
lists will generate a bus error. 


Example 
The following example demonstrates Getmpb, It prints out the amount of 
memory free and memory used. 


Winetude <osbind.he 
Winetude <bios.h> 


ong ehaceCep, me? 
char *ep; register struct edb ee; 


register long save, total 

struct me mab; 

printtcoxes\n", ep); 

total = 

shile (ap = (atruct mb #900) € 
save = Super(OL); mdb = "ep; Supertsaved; 
totals» eetamd size; 
princt(m\esDstar id bytes owned by Xx\n", 

indb.ne base, scueri size, meb.ze roe); 

np = neb.00 8 

5) 


printf(aid bytes total.\nt, roteld: 
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naingd € 
struct mpb eb; 
Getmpecacb): 
chase("Free Henery", mpb.mp free); 
chase( "Used Memory", =eb.mp used); 
return 


5} 


See Also 
bios, TOS 


‘getpal—Command 
Get the color palette settings 
getpal 
xetpal uses the xbios function Setpallete (sic) to read and return the current 
settings of the color palette. 
See Also 
commands, setpal, Setpallete, TOS 


getphys—Command 
‘Get the base of the physical screen's display 
getphys 
getphys is a command that uses the xbios function Physbase to obtain the base 
BE the screen display's physical memory. The address of the base is returned to 
the standard output, 
See Also 
commands, Physbase, setphys, TOS 


getrez—Command 
Get screen's current resolution 
getrez 


getrex is a command that uses the xbios function Getrez to read the screen's 
Current resolution, It returns to the standard output a code that indicates the 
current resolution, as follows: zero indicates high resolution; one, medium 
resolution; and two, low resolution, 

See Also 

commands, Getrez, setrez, TOS 
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Read the current screen resolution 
include <osbind-h> 

‘include <xbios.h> 

int Getrez() 


Getrez reads the current screen resolution, and returns the following: 


0 tow resolution 
1 medium resolution 
2 high resolution 


Example 
This program prints out the current resolution of the video display. For 
another example, see the entry for Prtblk. 


Hinelude <oubind.h> 
Hinelude <abios.to- 


struct restab € int rr 
‘e_LOv, Mow", 
(WED, Pecan, 
HIGH, highm, 
“1 Munk 


char *r name; reatabtl = ¢ 


4 
raing) ¢ 
repister struct rezteb * 


register int rez: 
p= Getrent)s 


tor (rp = rettab; mp-or_rer = rer b& rpor_rex I= 1; rp te 1) 


printf(mvour st is in Xs resolution mode.\nt, rp->r name); 
> 
See Also 
TOS, xbios 


STDIO function (tibe-a/gets) 

Read line from stream 

#include <stdio.h> 

char *gets(s) char * 

gets reads characters from the standard input into the string s, up to the next 
newline or EOF. It discards the newline, if any, appends a trailing NUL 
character, and returns s. 
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See Also 
STDIO 


Diagnostics 
gets returns NULL if an error occurs or if EOF is seen before any characters 
are read. 


Notes 
Unlike its cousin fgets, gets deletes newlines. 


Getshift—bios function 11 (osbind.h) 
Get or set the status flag for shift/alt/control keys 
‘include <osbind.h> 
winclude <bios-h> 
long Getshift(/iag) int flags 


Getshift gets or sets the status flag for the shift, alt, and control keys. If flag is 
<1, then the status flags of the keys are read and a map returned; if /lag is any 
number other than -1, then the flags are set to flag, and a map of their pre~ 
vious settings returned. The map is laid out as follows: bit 0, right shift key; bit 


1. left shift key; bit 2, control key, bit 3, alt key; and bit 4, caps lock key. If a 
bit is set to zero, the key is not depressed; if it is set to one, the key is 
depressed. 
Example 
This example displays characters, scan codes, and shift states until you type 
<ctrl-D>, 


include <oxbind.to 

include <bios.h> 

Hinetuse <etypest> 

struct shift ( (nt x.bitz char 4 name; > shift = © 
Gs_Usu, Mets ahites, 
GS_RSH, “right shite’, 
GSLETRL, Heontrol, 


as.ait, “alternates, 
CELeAPS, cape Lock, 
CEaws, | Hright mouse, 
teins, ete aeuse, 
Q 

a 

raind? ¢ 


register int ¢, 5 
register Long &: 
register stroct shift 
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6 = Beann(SE_CO¥; 
= Getsnifec-T); 
eect 19 get low word #7 
ce 2s 16; /* get sean code */ 

Beonout(8C RAW, 


Af Cisasctitey EE} isprintien? 
printt(m: “Re: *, cota"); 


else 
peintfets ter", ods 
printe(noabas8oanc8Oam, ce, €, 5); 


for (sp * shift; sp-rs.bit > 0; sp = 1) 
i (8B spos bit) 
princfC Dis)", sp-r5_nome 
print tenn: 
Didiile ce 1 OOH RF 49095 


> 


See Also 
bios, TOS 


Gettime—xbios function 23 (osbind.h) 
Read the current time 
#include <osbind.b> 
include <xbios.h> 
long Gettime() 
Gettime reads and returns the intelligent keyboard's setting of the current time, 
It returns a 32-bit mask whose bits indicate the following: 
‘no, of two-second increments (0-29) 
10. of minutes (0-59) 
no, of hours (0-23) 
day of the month (1-31) 
month (1-12) 
year (0-119, 0 indicates 1980) 


Example 

This example gets the keyboard time. Note that if you have not set the: 
keyboard time since you booted your computer, the time returned by this ¢x- 
ample will not be correct. 
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include <oobind he 


waint) ¢ 
register unsigned long tine; 
int seconde; 
int minutes: 
int hour: 
int dey: 
int month; 
int years 
tine = Gettinet); 
seconde = (tine & Ox001F) << 1p 
minutes = (tine 9 5) & OF: 
hours = (tie >> 11) & OxtF; 


dey = (time >> 16) & OATF; /* Bits 16; 
pronth = (time >> 21) £ Ox0F; —/* Bite 21:26 */ 
year = ((time >> 25) & OA7#}+1980; /* Bits 25:31 47 


printtcethe ATARL ST thinks {t (6 %d sec past Xd min\ni, 
seconds, minutes); 

printf(ipast the hour of Me*, hours); 

Printt oH on %a/Rd/Ad\ne", menth, day, veer): 


ey 
For another example of this function, see the entry for time, 


See Also 
Kgettime, Settime, time, TOS, xbios 


Notes 


‘The time data in the bit map returned by Gettlme is in exactly the reverse order 
of the data returned by the gemdos functions. 


getw—STDIO function (libe.a/getw) 
Read integer from stream 
#lnclude <stdio.h> 
int getw(/p) FILE */r; 


getw reads @ word (an int) from the stream fp. 


See Also 
gete, STDIO 


Notes 

getw returns EOF on errors. A call to feof or ferror may be necessary to distin— 
guish this value from a valid data word. The bytes of the word it receives are 
assumed to have been written by putw, which writes them in the natural byte 
ordering of the machine. 
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Giaccess—xbios function 28 (osbind.h) 
Access a register on the GT sound ci 
#include <osbind.b> 
#include <xbios.h> 
char Giaceess(data, register) char data; int register; 


Giaccess accesses a register on the GT sound chip. register is the name of the 
register being accessed, zero through 15. Bit 7 of this variable indicates 
whether this register is to be read or written to: zero indicates read, one in- 
dicates write, date is the eight-bit value being passed to the register when this. 
macro is in write mode; if Giaccess is in read mode, this value is ignored. 


Giaceess returns the value réad if in read mode, and a meaningless value if in 
write mode. 


The Atari ST's sound generator is controlled by 16 eight-bit registers. The 
sound generator itself has three channels, named A, B, and C, Each can be 
programmed independently. Nose that the contents of the address register 
remain unaltered until reprogrammed, which allows you to use the same date 
repeatedly without having to resend them. What each register does is listed in 
the following: 


0,1 Set pitch and period length for channel A. The eight bits of register 0 
set the pitch, and the first four bits of register | control the period 
length; the lower the number formed by the 12 significant bits of these 
registers, the higher the pitch of the tone generated. 


2,3 Set the pitch and period length for channel B. 
4.8 Set the pitch and period length for channel C. 


6 The low five bits of this register control the generation of “white 
noise"; the smailer the value to which these bits are set, the higher the. 
pitch of the noise generated. 


7 This register holds an eight-bit map whose bits toggle various aspects of 
sound generation; for each bit, zero indicates on and one indicates off. 
The bits control the following functions: 


Channel A tone 

‘Channel B tone 

‘Channel C tone 

Channel A white noise 
Channel B white noise 
Channel C white noise 
Port A; O-input, I-oulput 
Port B; O=input, |=output 


sous 
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9 
10 
11,12 


13 


14,15 


Bits 0 through 3 set the signal yolume for channel A; the settings can be 
zero through 15, with zero being the softest setting and 15 the loudest. 
Setting bit 4 indicates that the “envelope” generator, register 13, should 
be used; in this case, the contents of bits 0 through 3 are ignored, 

Same as register 8, only for channel B. 


‘Same as register 8, only for channel C. 


Control tone generation, A tone is constructed of four aspects: attack, 
decay, sustain, and release. Attack defines how long a tone takes to 
reach is loudest point, decay’ defines how long that loudest point is held 
before it softens to the volume that is sustained; sustain defines how 
Jong the sustained level is held; and release defines how long it takes a 
tone to decay into silence. These registers govern the four aspects of 
tone generation, register 11 holds the low byte, register 12 the high byte. 


Bits 0 through 3 set envelope generator’s waveform, A tone’s “en- 
velope” is the “shape” of the tone generated, which is best studied oy 
experimental listening. 


Control the Atari ST's 1/O ports. Register 14 controls port A, and 
register 15 port B, If set to output by register 7, the contents of these 
registers can be exported. Note that these ports have nothing to do with 
sound generation, and are used on the Atari ST to control the floppy 
disk drives. 


Example 
This example uses Giaccess to set the select lines for the floppy disk drives. It 


is not 


recommended that this be done from user programs in general. 


include <osbind.h> 


prompt¢strna) Jf Write prompt; wait for key to be typed */ 
cher *strng7 
c 


Ceonwecstrng); /* Urite the string */ 
Cravcin(); 7 Wait for 8 key */ 
Ceonascn\r\n;  / CRLF to console */ 


GMT-gmtime 


rained € 
prompt(Let drives stop; then press aty key to continue"); 
Ginccess((Gisccess(0,14) & OxF8),14|0380); 
prompt ("Soth Lights on... Hit any key!) 
Giaccess((Gisccess(0,16) & OxF8)|2, 16) 0x80); 
prompt(*Drive 8 selected... Hit any key"); 
Slaccess((Giaccess(0,14) & OxF8)|4,14|0x807; 
pronpt(Drive A selected... Hit any key") 
Giaccess(¢Giaccess(0,14) & OxFB) [6,14 [0x80 
ppronpt (Neither erive selected... Hit any key! 
Peer: 


> 
See Also 

Offgibit, Ongibit, TOS, xbios 
Programmable Sound Generator Data Manuat 


GMT—Definition 
GMT js an abbreviation of Greenwich Mean Time, the time recorded at the 
Greenwich Observatory in England, where by international convention the 
Earth’s 0 meridian is fixed, 


‘See Also 
‘gmtime, localtime, time.h, TIMEZONE 


gmtlme—Time function (libe.a/etime) 

Convert system time to system calendar structure 
Jude <time.h> 
tm_t *gmtime(timep) time_t *timep; 


gmitime converts the internal time from seconds since midnight January 1, 1970 
GMT, into fields that give integer years since 1900, the month, day of the 
month, the hour, the minute, the second, the day of the week, and yearday. It 
returns a pointer to the structure tm_t, which defines these fields, and which is 
itself defined in the header file time.h. Unlike its cousin, localtime, gmtime 
returns Greenwich Mean Time (GMT). 


Example 
For an example of how to use this function, see the entry for asctime. 
See Also 

localtime, time 

Notes 


gitime returns a pointer to a statically allocated data area that is overwritten by 
Successive calls, 
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graf_dragbox—AES function (libaes.a/graf_dragbox) 
Draw a dragable box 
#include <aesbind.h> 
int graf_dragbox(width, height, startx, starty, boundary, &finishx, &finishy) 
int width, height, startx, starty, finishx, finishy; Rect Boundary, 


graf_dragbox is an AES routine that allows the user to drag @ box within 2 
specified boundary rectangle. The boundary rectangle puts limits on how far 
the box can be dragged; it can be set to the entire screen, to @ window, or to 
some other boundary, 


width and height ive, respectively the width and height of the box, in rasters. 
Note that the number of raster on the screen varies with the degree of screen 
resolution; the following gives the dimensions of the screen in rasters, by 


resolution: 
Resolution Width Height 
High 640 400 
Medium 640 200 
Low 320 200 


startx and starty give, respectively, the starting X and Y coordinates for the 
box. finishx and finishy hold the coordinates after the box has been dragged; 
these values are set by the function. 


boundary is the outline of the boundary rectangle. It is declared to be of type 
Reet, which is defined in the header file aesbind.b. Rect consists of four 
elements: 
x X coordinate of rectangle 
y  ¥ coordinate of rectangle 
w width of rectangle 
h height of rectangle 
graf_dragbox returns zero if an error occurred, and a number greater than zero 
if one did not. 
Example 
For an example of this function, see the entry for yro_epyfm. 
‘See Also 
AES, TOS 
Notes 


graf_dragbox returns when the mouse button is released. If it is called while 
the mouse button is up, it returns immediately. 
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graf, 


grat 


}_growhox—AES function (libaes.a/graf_growbox) 


‘Draw a growing box 
#include <aesbind.h> 
int graf_growbox(small, big) Rect small, bigs 


graf_growbox is an AES routine that draws a growing box on the sereen, The 
box drawn by graf_growbox does not stay on the soreen; this routine is 
designed merely to add a “star wars”-style flourish to GEM programs. The ar 
guments smal/ and hig are both defined as being of type Rect, which is defined 
in the header file aesbind.h, Rect consists of four elements: 


x X coordinate of rectangle 
y  Y coordinate of rectangle 
w width of rectangle 
hh height of rectangle 
The box grows from the dimensions described in small to those described in 


large. The unit of measure is the number of rasters for the screen; the number 
of rasters held by the screen varies with the degree of resolution, as follows: 


Resolution Width Height 


High 640 400 
Medium 640 200 
Low 320 200 


graf_growbox returns zero if an error occurred, and a number greater than zero 
if of@ did not, 


Example 
For an example of this routing, see the eatry for window. 


See Also 
AES, gem, graf_shrinkbox, TOS, window 


handle—~ALS function (libaes.a/graf_handle) 


~ Get VDI handle 
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#include <aesbind.h> 
int graf_handle(chwidth, chheight, hwidth, bheight) 
int *chwtdth, *chheight, *bwidsh, *theigits 


graf_handle is an AES routine that returns the VDI handle for the “virtual 
workstation", or the physical device on which you are working; it also returns 
the size of the font with which you are working. It returns the current VDI 
haadle. chwidth and chheight point, respectively, to the character width and 
character height of the font being used. bwidth and bheight point to the width 
and height of the box in which a character is displayed. In effect, the dif- 
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ference between the character size and the box size governs how much “white 
space” surrounds each character. These values are set by GEM. 


See Also 
AES, TOS 


graf_mbox—AES function (libaes.a/graf_mbox) 


“Move a box 

#include <aesbind,h> 
Int graf_mbox(wideh, height, fromx, from: 
int width, height, fromx, fromy, tox, toys 


geaf_mbox is an AES routine that moves a box without changing its size. width 
End Tieight are the dimensions of the box. fromx and fromy give the original 
position of the box: tox and foy the destination position of the box. Note that 
both of these pairs of coordinates refer to the upper left-hand corner of the Box 
being moved. graf_mbox returns zero if an error occurred, and « number 
greater than zero if Gne did not. 


See Also 
AES, TOS 


9, tox, tay) 


graf_mkstate—AES function (libaes.#/graf_mkstate) 


Get the current mouse state 
#include <aesbind.h> 
int graf_mkstate(record) Mouse recard; 
graf_mkstate is an AES routine that returns the current mouse state. record is 
Heclared to be of type Mouse, which is a structure of four pointers to integers 
that is declared in the header file neshind.h, as follows: 
x X coordinate of mouse pointer 
y  ¥ coordinate of mouse pointer 
) button state when event occurred 
k state of control, alt, and shift keys: 
0x0; all Keys up 
Ox1: right shift key down 
Ox2: left shift key down 
Ox4: control key down 
Ox8: alt key down 


‘These values are set by GEM. 
graf_mkstate always returns one. 
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See Also 
‘AES, TOS 


‘graf _mouse—AES function (libaes.a/graf_mouse) 
Change the shape of the mouse pointer 
#include <aesbind.h> 
int graf_mouse(form, definition) int form; char *de{initions 
graf_mouse is an AES routine that changes the mouse pointer from the default 
arrow to another shape. form is an integer that indicates what new shape you 
‘want, as follows: 
0 Arrow (default) 
1 Vertical tine 
2 Bee 
3° Hand with pointing finger 
4 Hand with extended fingers 
5 
6 


‘Thin cross hairs 
Thick cross hairs 
7 Outlined eros hairs 

285 Use user-described shape 

256 Hide mouse pointer 

257 Display mouse pointer 
definition points to  35-word block in which the user has specified her new 
pointer shape. This argument is ignored if form is any value other than 255, 
graf_mouse returns zero if an error occurred, and a number greater than zero if 
one did not. 
Example 
‘The following example cycles through the preset shapes for the mouse pointer. 


#inelude <aesbind. 


mmaing) € 
int nownerey 1* Soneplece to point */ 
appl into; 
for (counter = 0; counter <7; counterss) 
raf mouse(counter, Snowhere); 
ent keyed); 7 Hatt until a key it typed */ 
> 
sopl exit; 
exittD); 
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Mark Williams C 


For further examples, see the entries evt_multi, object, window. 


See Also 
AES, abject, TOS, window 


graf_rubbex—AES function (libaes.a/graf_rubbox) 


Draw a rubber box 

include <aesbind.h> 

int graf_rubbox(hox, newwidth, newheighe) 
Rect bo int *newwideh, *newhelghes 


graf_rubbox is an AES routing that draws a “rubber box" on the screen; a rub- 
ber Box is one whose dimensions can be altered by the user. box defines the in- 
jtial dimensions of the rubber box. It is of the type Rect, which is defined in 
the header file aesbind.h, Rect consists of four elements; 

x X coordinate of rectangle 

y  ¥coordinate of rectangle 

ww width of restangle 

h height of rectangle 


newwidth and newheight point to the values for width and height to be set by 
the user. 


‘This routine can be used to define a block of screen area that can be copied 
elsewhere, For example, the GEM desktop routine that allows you to click 
more than one file at a time employs graf_rubbox. 

graf_rubbox returns zero if an error occurred, and a number greater than 2er0 
if one did not. 

Example 

For an example of this routine, see the entry for ¥_bar. 


See Also 
AES, TOS 
Notes 

This routin 


often called graf_rubberbox in other bindings. 


graf_shrinkbox—AES function (libaes.a/graf_shrinkbox) 


Draw a shrinking box 

#include <aesbind.h> 

int graf_shrinkbox(smallbox, bigbox) Rect smallbox, bigbox, 
graf_shrinkbox is an AES routine that draws a shrinking box on the screen, 


The box drawn by graf_shrinkbox does not stay on the screen; this routine is 
designed merely to add a “star wars”-style flourish to GEM programs, The ar- 
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guments smallbox and bigbox are both defined as being of type Reet, which is 
defined in the header file aesbind.h. Rect consists of four elements: 

x X.coordinate of rectangle 

y  Y coordinate of rectangle 

w width of rectangle 

h height of rectangle 


The box grows from the dimensions described in smallbox to those described in 
lorge. The unit of measure is the number of rasters for the screen, as follows: 


Resoluion Widih — Height 


High 640 400 
Medium 640 200 
Low 320 200 


graf_shrinkbox returns zero if an error occurred, and a number greater than 
zero if one did not. 


Example 
For an example of how to use this routine, see the entry for window, 


See Also 
‘AES, gem, graf_growbox, TOS 


graf_slidebox—AES function (libaes.a/graf_slidebox) 
‘Track the slider within a box 
#include <aesbind.h> 
Pinclude <obdefs.h> 
int geaf_slidehox(:rce, parent, slider, direction) 
char *1r2e: int parent, slider, direction; 


graf_slidebox is an AES routine that tracks the movement of the “slider” 
within a box. The “slider” is the area of the window that the uset can click to 
scroll through the contents of the file or directory being displayed in the win- 
dow. 


{ree points to the address of the object tree that contains the slider. pareut is 
the index of the parent object within the object tree, and slider is the index of 
the slider object. direction is the direction of movement relative to the position 
of the parent object; zero indicates horizontal movement and one indicates yer- 
tical movement. graf_slider returns the position of the center of the slider 
relative to the parent object. If movement is vertical, then zero indicates the 
topmost position and 1,000 the bottom-most; and if movement is horizontal, 
then zero indicates the leftmost position and 1,000 the rightmost, 


260 Mark Williams C 


Lexicon graf_watehbox 


See Also 
‘AES, TOS 


graf_watchbox—AES function (libaes.a/graf_watchbox) 
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Draw a watched box 

#include <aesbind.h> 

#include <obdefs.h> 

int graf_watchbox( ree. object, insidepattern, outsidepattern) 
OBJECT "iree; int object. insidepatiern outsidepattern, 


graf_watchbox is an AES routine that draws a “watchable box”, that is, a box 
that the screen manager can poll to see if the mouse pointer is inside it or out- 
side it. The user must hold down the leftmost mouse button while moving the 
pointer; graf_watchbox returns the position the pointer was at when the button 
was released, 


tree points to object tree that produces the box in question. object is the index 
of this object within the tree, insidepattern and oulsidepattern indicate, respec- 
tively, the pattern used to fill the area within the box and outside the box, as 
follows; 


normal 
selected 
crossed 
checked 
outlined 
shadowed 


aueune 


graf_watchbox returns a value that indicates whether the mouse pointer was 
inside or outside the box when the buiton was released: zero indicates outside, 
aad one indicates inside. 
‘See Also 

AES, TOS 
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handle—Definition 
A handle is a generic term for a unique identifier used by TOS and GEM. 
Three types of handles are commonly used: file handles, workstation handles, 
and process handles. 


A file handle is identifies a source of bits; it can refer either to a file on disk ar 
toa character device. File handles are returned by fopen, ferent, and fdup, and 
are used by fwrite, fread, and fseek. 


A workstation handle is used by the GEM VDI to identify a virtual device. Tt is 
returned by the routines v_opnwk and y_opnywk, and is always the first argu- 
ment accepted by 2 VDI routine. 


A process handle identifies a process that runs under the AES. At present, 
these handles have only limited vse, because the AES currently can run only 
one process at a time, 


See Also 
AES, VDI, UNIX routines 


header file—Definition 
A header file is a file of text that conteins definitions, declarations, and struc- 
tures commonly used in a given situation. By tradition, a header file always has 
the suffix “.h*, Header files are invoked within a C program by the command 
include, which is read by epp, the C preprocessor; for this reason, they are also 
called “include files”. 
Header files are one the most useful tools available to a C programmer. They 
allow you to put into one place all of the information that the different modules 
of your program share. Proper use of header files will make your programs 
much easier to maintain and port to other environments, 
See Also 

clude, math.h, portability, stdio.h 


help—Command 
Print concise description of command 
help command 


help prints a concise description of the options available for each specifed com- 
mand. Wf the command is omitted, help prints a simple description of itself, ‘The 
primary purpose of help is to refresh the memory of a user who has forgotten a 
command option, 


Information used by help is kept in the file named helpfile. Information about = 
command begins with a line 
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#eommand 
and ends with the next Tine beginning with ‘#'. If you wish, you can edit this 
file and add new descriptions for commands that you want to run under msh. 


See Also 
‘commands, msh 


hidemouse—Command 
Hide the mouse pointer 
hidemouse 


hidemouse is a command that uses the function lineaa to hide the mouse 
pointer. Note that if hidemouse is used when the mouse pointer is already hid- 
den, the mouse pointer will need to be called twice before it reappears. 

See Also 

commands, Line A, showmouse, TOS, 


HOME—Environmental parameter 
HOME names where the micro-shell msh should look for a file when no other 
directory is specified. For example, if you type the ed command without an ar- 
gument, msh will change the directory to the one you named as the HOME 
directory. 


It is set with the seteny command, 


See Also 
msh, setenv 


horizontal tab—Definition 
‘Mark Williams C recognizes the literal character *\t' for the ASCIT horizontal 
tab character HT (octal 011). ‘Thi character may be used as @ character con~ 
stant or in a string constant, like the other character constants: ‘\a’, which rings 
the audible bell on the terminal; ‘\b', to backspace; *\f", to pass a formfeed 
command to the printer; “\r', for a carriage return; and “\v’, for @ vertical tab 
character, 


See Also 
ASCII, character constant 


htom—Command 
Redraw screen from high to medium resolution 
htom 
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Hom is a command that redraws the screen, moving from high to medium 
resolution, 


See Also 
commands, Itom, mtoh, mtol, TOS 


hypot—Mathematics function (libm.a/hypot) 
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‘Compute hypotenuse of right triangle 

‘#include <math.h> 

double hypot(x, y) double x,y: 

hypot computes the hypotenuse, or distance from the origin, of its arguments x 
and y. The result is the square root of the sum of the squares of x and y. 
Example 

For an example of this function, see the entry for acos. For an example of its 
‘ue in a GEM-DOS zpplication, see the entry for v_circle, 

See Also 

cabs, mathematics library 
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{skbdws—xbios function 25 (osbind-h) 
Write a string to the intelligent keyboard device 
#include <osbind.h> 
#include <xbios.h> 
void Tkbdws(umber. buffer) int number; char *buffery 


Ikbdws writes a string of characters to the intelligent keyboard, number is the 
number of characters to write, minus one, and buffer points to the buffer 
where these characters are kept. 

‘The Atari ST’s intelligent keyboard can accept many commands that affect the 
keyboard itself, the mouse, and the joystick, For more information on how the 
intelligent keyboard manipulates these devices, see the entry for Kbdybase. 

See Also 

Geitime, Khdvbase, Settime, TOS, xbios 


INCDIR—Environmental parameter 
INCDIR names the default directory in which ce looks for files to be included 
during compilation. The directory that contains the source files and directories 
named in the -I option to the ce command are also searched for include files. 
To set INCDIR, use the setenv command, 


See Also 
#include, msh, setenv 


#include—Definition 
#include <fileh> 
#include "file.h" 


clude is 4 statement processed by the C preprocessor epp. Its operation is 
Simple: the preprocessor replaces the #include statement with the contents of 
file 


The name of the file can be enclosed within angle brackets (</ife.h>) or quota- 
tion marks ("file.h"). Angle brackets tell epp to look for fife.h in the direc- 
tories named with the -/ option to the ec command line, and then in the stan— 
dard directoty, in this instance the directory named by the INCDIR envirca. 
mental parameter. Quotation marks tell ep to look for filesh in the source 
file's directory, then in directories named with the -I option, and then in the 
standard directory. 


Files that are called with #include statements are called header files or include 
files. 
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See Also 
ep, header file, msh 
The C Programming Language, page 207 


include file—Definition 
Include file is another name for a header file. 


See Also 
header file 


index—String function (libe.a/index) 
Find a character in a string 
char findex(string, c) char *string; char c; 


index scans the given string for the first occurrence of character ¢. If ¢ is 
found, index returns a pointer to it. If it is not found, index returns NULL. 


See Also 
string 
The C Programming Language, page 67 


Initmous—xbios function ( (osbind.h) 
Initialize the mouse 
#include <osbind.h> 
#include <xbios.h> 
void Tnitmous(ty;pe, parameter, vector) 
int type; char *parameter; long vector; 


Initmous initializes the mouse, and returns nothing, 
Lype indicates the mode into which the mouse is to be set, as follows 
0 turn mouse off 


1 enable in relative mode 
2 enable in absolute mode 
3 unused 


4 enable in keycode mode 


parameter is the address of the 14~byte parameter block. Bytes 0 through 3 are 
used under all modes; bytes 4 through I1 are used only if the mouse is in- 
itialized into absolute mode. The parameter block's bytes indicate the 
following: 

0 non-zero, set Y axis 0 at bottom; zero, set Y axis 0 at top 

1 set the parameter for command to set mouse buttons 

2 set parameter for X axis threshhold~scale-delta 

3. set parameter for Y axis threshhold-scale-delta 
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4 most significant byte (MSB) for mouse’s absolute maximum 
position on X axis 

5 least significant byte (LSB) for mouse’s absolute maximum 

position on X axis 

‘MSB for mouse's absolute maximum position on Y axis 

LSB for mouse’s absolute maximum position on ¥ axis 

MSB for mouse's initial position on X axis 

LSB for mouse’s initial position on X axis 

‘MSB for mouse’s initial position on ¥ axis 

LSB for mouse’s initial position on ¥ axis 


weetor gives the mouse's interrupt vector routine. 


See Also 
TOS, xbios 


int—Definition 
An int is the most commonly used numeric data type, and is normally used to 
encode integers. On the 68000, as on most microprocessors, sizeof int equals 2, 
that is, two chars (15 bits plus a sign bit); therefore, an ini can contain values 
from -32768 to +32767. An int normally is sign extended when cast to a larger 
data type; an unsigned int, however, will be zero extended. 


See Also 
data types, declarations, long 


interrupt—Definition 
"An interrupt is an interruption of the sequential flow of a program, Te can be 
generated by the hardware, from within the program itself, or from the 
operating system. 


‘The functions bios, gemdos, and xbios all employ traps, a form of interrupt, 10 
perform their respective tasks. 


See Also 
bios, gemdos, xbios 


Torec—xbios function 14 (osbind.h) 
Set the 1/O record 
include <osbind.h> 
‘include <xbios.h> 
iorec *lorec(device) int device; 


Toree returns 8 pointer to a serial device's input buffer record. device is an in 
teger that encodes the serial device: the legal settings are 0, 1, or 2, far the RS- 
232 port, the keyboard, or the musical instrument device interface (MIDI) port, 
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respectively. 


‘As noted, Toree returns a pointer to the device's input buffer record. The 
record is a structure that is laid out as follows: 


struct foree ¢ 


char “fo_butty fr Butter */ 
short fo_bufsiz; ff Buffer size in bytes */ 
short JF Current urite pointer * 
short 7 Current read pointer */ 


short io_low 7 Low water mark, unstop Line */ 

short fo_high: 7 High water mark, stop Line */ 
> 
huffer points to the device's buffer. size is the buffer's size; high is its “high 
water mark”, or where an XOFF is sent to the transmitting device; and low is 
its “low water mark”, or the point where an XON is sent to the transmitting 
device. Finally, head is the head index and tail the tail index, Note that for the 
RS-232 port, the input-buffer record is followed by an output-buffer record 
that is structured exactly the same. 
Example 
This example examines all of the input devices and displays their buffers. For 
an example of using this function from the \auto directory, see the entry for 
\auto. 


Hinelude <osbind n> 
Hinelude <xbios.h> 


coump¢ptr) 
segister struct forec tptr: € 


ptr->fo tail = ptre>io head) < 0) 
ceount = per-pfe_Bufel; 


printf(iguffer at lx has 4d out of td characters in ft.\n", 
ptr-vie buff, ecount, ptr->io butsi2: 


printfCHLWH et Sd characters, sum at td characters\n", 
ptr-rio low, ptr->to high); 
> 
main 
struct iorec *tp; 
bp = torect9): 7 get 1/0 buffer for serial port */ | 
print#(userial port input but fer:\nM 
odanpcbp); 
printfovserfal port output buffer: \n); 
betes 
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iodunptop): 
bp = Lerect1): /* Now for the keyboerd */ 
print f(Keyboard input buffer:\nt; 
Fodunecbp): 
bp = forect2y; J MIDE input buffer */ 
printfCoMIDT input buffers\nt 
Fodunp¢bp): 

> 

See Also 


TOS, xbios 


isalnum—etype macro (ctype-h) 
Check if a character is a number or letter 
‘include <ctype-h> 
isalnum(c) int c; 


isalnum tests whether the argument c is alphanumeric (0-9, A~Z, or a-z), It 
returns non-zero if ¢ is of the desired type, zero if it is not. isalnum assumes 
that ¢ is an ASCII character or EOF. 

Example 

For an example of how to use this macro, see the entry for ctype. 


See Also 
ctype 


isalpha—ctype macro (ctype,h) 
Check if a character is.a letter 
include <etype-h> 
isalpha(c) int ¢ 


isalpha tests whether the argument c is a letter (A~Z or az), Tt returns non- 
zero if ¢ is, zero if it is not. isalpha assumes that c is an ASCII character or 
EOF. 

Example 

For an example of this macro, see the entry for ctype, 


See Also 
ctype 


isaseiictype macro (etype.h) 
Check if a character is an ASCIT character 
include <ctype.h> 
isascli(c) int 3 
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isascii tests whether the argument ¢ is an ASCII character (0 <= ¢ <= 0177). It 
returns non-zero if ¢ ig an ASCII character, zero if it is not. Many other ctype 
‘macros will fair if passed non-ASCII values other than EOF. 


Example 
For an example of how to use this macro, see the entry for type. For an ex- 
ample of its use in a TOS application, see the entry for Fgetdta, 


See Also 
ASCII, ctype 


isentrl—ctype macro (ctype-h) 
‘Check if a character is a control character 
include <ctype.h> 
isemtel(c) int ¢; 


isentrl tests whether the argument c is a control character (including a newline 
character) or a delete character. It returns non-zero if c is of the desired type, 


zero if it is not, isentrl assumes that ¢ is an ASCII character or EOF. 
Example 

For an example of how to use this macro, see the entry for ctype. 
See Also 

ctype 


isdigit—ctype macro (ctype;h) 
Check if a character is a numeral 
#include <ctype.h> 
sdigit(c) int cj 
isdigit tests whether the argument ¢ is a numeral (0-9). Tt returns non-zero if ¢ 
is of the desired type, zero if it is not. isdigit assumes that c is an ASCIL 
character or EOF. 
Example 
For an example of how to use this macro, see the entry for etype. 
See Also 
ctype 


isleapycar—Time function (libe.a/isleapyear) 
Indicate if a year was a leap year 
¥include <time.h> 
Int isleapyear(year) int year; 
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isleapyear indicates whether a given year A.D. is a leap year or not. year is the 
year A.D. in which you are interested. Isleapyear returns zero if year was not a 
leap year, and a number greater than zero if it was, 

‘See Also 

dayspermonth, time, time.h 


islower—ctype macro (ctype-h) 
Check if a character is a lower-case letter 
#include <ctype.h> 
islower(c) int ¢; 
islower tests whether the argument c is a lower-case letter (a-z). Tt returns non- 
zero if ¢ is of the desired tyne, zero if it is not, islower assumes that ¢ is an 
‘ASCII character or EOF. 
Example 
For an example of how to use this macro, see the entry for ctype. 
See Also 
ctype 


print—ctype macro (ctype.h) 
Check if a character is printable 
#include <ctype.h> 
isprint(c) int c 
isprint is a macro that tests whether the argument ¢ is printable, i.e, whether it 
js neither a delete nor a control character. It returns non-zero if c is of the 
desired type, zero if it is not. isprint assumes that ¢ is an ASCII character or 
EOF. 
Example 
For an example of how to use this macro, see the entry for etype. 


See Also 
ctype 


ispunet—ctype macro (ctype-h) 
‘Cheek if a character is a punctuation mark 
#include <ctype.h> 

spunet(c) int c 


ispunct tests whether the argument c is a punctuation mark, i.e., neither an al- 
phanumoric character nor a control character, Tt returns non-zero if the 
character tested is of the desired type, zero if it is not. ispunct assumes that c is 


Mark Williams C 271 


upper Lexicon | 


an ASCTI character or EOF. 


Example 
For an example of how to use this macro, see the entry for ctype. 


See Also 
ctype 


isspace—ctype macro (etype.h) 
Check if a character prints white space 
include <etype.h> 
isspace(c) int c; 
sspace tests whether the argument c is space, tab, newline, carriage return, or 
form-feed character. It returns non-zero if ¢ is of the desired type, zero if it is 
not. isspace assumes that ¢ is an ASCII character or EOF, 
Example 
For an example of how to use this macro, see the entry for etype 


See Also 
ctype 


isupper—ctype macro (ctype.h) 
Check if a character is an an upper-case letter 
#include <ctype.h> 
isupper(c) int c 
supper tests whether the argument c is an upper-case letter (A~Z). Tt returns 
non-zero if cis of the desired type, zero if it is not. isupper assumes that ¢ is 
an ASCII character or EOF, 


Example 
For an example of how to use this macro, see the entry for ctype. For an ex- 
ample of its use in ¢ TOS application, see the entry for Fgetdta. 


See Also 
‘ctype 
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j0—Mathematics function (Iibm.a/j0) 
Compute Bessel function 
include <math.h> 
double j0(=) double =; 


j0 takes the argument = and computes the Bessel function of the first kind for 


‘order 0, 


Example 
This example, called bessel. 
it with the following command line 


ee -f bessel.c -Im 
to include floating-point functions and the mathematics library. 


‘inetude <nathhe 
Gedisplaycvatue, name) 
double value: char *rane: 
4 
if (errno) 
perror(name); 


else 
pringfenetog Xe\n", volue, mane): 
errno = 0; 


iy 


sastine display(x) dedispley¢¢doubter(x, "%" 
rain € 

extern char *9ets00s 

sdovbt= 

char stringt6ll; 


forts2) ¢ 
printf(lenter numbers "7 
ffigetststring) 
break; 
= ateftstringd 


Sisplayoa 
displey(JOCx03; 
display( 100: 
ssisplaytJaC0, 200s 


display jaca) 
sisplay(in(2,29 
display(nG3,4)); 
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See Also 
Hi, ja, mathematies library 


J1—Mathematics function (libm.a/j1) 
Compute Bessel function 
#include <math,h> 
double j1(z) double =; 
i] fakes the argument z and computes the Bessel function of the First kind for 
order 1 
Example 
For an example of this function, see the entry for j0. 
See Also 
J0, jn, mathematics library 


Jday_to_time—Time function (iibe.a/Jday_to_time) 
Convert Julian date to system time 
include <time.h> 
time _{ jday_to_time(time) jday_t times 


Jday_to_time converts Julian time to system time. time is the Julian time to be 
converted. It is of type jday_t, which is defined in the header file time.h, 
jéay_t is a structure that consists of two unsigned longs. The first gives the 
number of the Julian day, which is the number of days since the beginning of 
the Julian calendar (January 1, 4713 B.C.). The second gives the number of 
seconds since midnight of the given Julian day. 


Jday_to_time returas the Julian time as converted to type time_t: this typo is 
defined in the header file time.h as being equivalent to a long. Mark Williams C 

jefines the current system time as being the number of seconds from January |, 
1976, OhOOmO0s GMT, which is equivalent to the Julian day 2,440,587. 


See Also 
jéay_to_tm, time, time.h, time_to_jday, tm_to_jday 


Note 
‘Tris function mainly is of use to astronomers, geographers, and historians, 


jday_to_tm—Time function (libe.a/jday_to_tm) 
‘Convert Julian date to system calendar format. 
#include <time.h> 
tm_t *jday_to_tm(time) jday_t time; 
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jday_to. tm converts Julian time to the system calendar format. time is the 

Julan time to be converted, It is of type jday_t, which is defined in the | 
hheader file time.h. jday_t is a structure that consists of two unsigned longs. The 

first gives the number of the Julian day, which is the number of days since the ) 
beginning of the Julien calendar (January 1, 4713 B.C.), The second gives the 
number of seconds since midnight of the given Julian day. 


jday_to_tm returns a pointer to a copy of the structure tm_t, which is defined 
jn the Header file timeh, For more information on this structure, see the 
Lexicon entry for time, 


See Also 
jday_to_time, time, time.h, time_to_jday, tm_to_jday 


Note 
‘This function is of use mainly to astronomers, geographers, and historians | 


Jdisint—xbios function 26 (osbind.h) 
‘Disable interrupt on muli-function peripheral device 
#include <osbind-h> 
include <xbios.h> 
void Jdisint(number) int number; 


Jdisint disables an interrupt on the multi-function peripheral device, end 
Teturns nothing, mumber is the number of the interrupt to disable, For a table 
of interrupt codes, see the entry for Mfpint. 


See Also 
Jenabint, Mfpint, TOS, xbios 


Jenabint—xbios function 27 (osbind.h) 
Enable a multi-function peripheral port interrupt 
#inelude <osbind.h> 
include <xbios.h> 
yoid Jenabint(mumbder) int numbers 
Jenabint enables the multi-function peripheral (MFP) interrupt, and returns | 
hothing. number is the number of the interrupt to disable. For a table of inter | 
rupts, sce the entry for Mfpint. 
See Also 
‘Jlisint, Mfpint, TOS, xbios | 


jn—Mathematics function (libm.a/jn) 
Compute Bessel function 
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‘#include <math.h> 
double ja(, 2) int m; double =: 


Jn takes an argument 2 and computes the Bessel function of the first kind for 
order 1. 

Example 

‘For an example of this function, see the entry for j0. 


‘See Also 
40, j1, mathematics library 
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Kbdybase—xblos function 34 (osbind-h) i 
Return a pointer to the keyboard vectors 
clude <osbind.h> I 
include <xbios.h> 
kbdvbase *Kbdybase() 


Kbdybase returns a pointer to a structure that holds the following elements: 


struct Kidvbase © 
void (*ke midivecdO: 


‘J IDE input date vector */ 


void (#kb.vkbserr)C; ‘7* keyboard error vector */ 
void (kb ymiserr) 7 MI01 error vector */ 

Void (kb statvec)O} + keyboard status packet */ 
void (#kb_mousever)( ‘7+ keyboard nouse packet */ 
Void (kb clockvecO; ‘= keyboard clack packet */ 
void (kb jovrecdO; ‘/* keyooard joystick packet */ 
Void (rkb midisys)(2 [system mia vector */ 

void (kb Kedsys) 7 (7 system keyboard vector */ 


% 


midivee points to a routine that moves data from the musical instrument digital 
interface (MIDI) into the MIDI buffer, 


kb_vkbderr and kb_vmidere point to routines that ate called whenever an error 
condition is detected, respectively, on the intelligent keyboard or on the MIDI. 


kb_statvee, kb_mousevec, kb_clockvec, and kb__ point to routines that process 
Gaia received Trom, respectively, the intelligent keyboard status handler, the 
mouse, the clock, and the joystick. 


Finally, kb_midisys and kb_ikbdsys point to routines that call handlers when 
characters Become available for respectively, the MIDI and the intelligent 
keyboard. 


Manipulating peripheral devices 

By default, the keyboard reports each make/break contact om the joystick port, 
gach make/break contact on the mouse buttons, and each movement of the 
mouse that exceeds a preset threshold. Each report consists of a “packet” of 
three bytes that indicate which device is changing and what change took place. 
Note that the packet for the joystick has been documented elsewhere as consis 

ting of two bytes, this is incorrect. 


“The joystick packets consist of three bytes: The first is always OxFF, which in— 
dicates jaystick vent on port 1; the second is filler, and is always 0x00; and 
third records the closed switches on the joystick as set bits in the low aybble. 
Technically, the high bit of the third byte should encode the state of the joys- 
tick fire button, In the default set-up, the fire button is set to the left mouse 
button. ‘This will change if you instruct the Keyboard to adopt some other 
reporting mode. 
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The mouse packets consist of three bytes: The first is 0xF8, which indicates 
relative mouse event and encodes the state of the mouse buttons and joystick 
fire button in the low bits of the low nybble The second and third encode, 
respectively, the relative X- and Y-axis motion as signed characters. 


If you do not have a joystick, you can simulate one by plugging your mouse 
into the joystick port, The mouse quadrature signals shaw up as the north south 
east west switch closure bits in the joystick packet. Tn addition, the left mouse 
‘button still shows up as a mouse event, but the right button is inoperative. 


Example 
‘The following example monitors the keyboard's mouse and joystick vectors, 


include <osbing.h> 
finelude <bios.h> 
Hinelude <xbios.h> 


J* twonslate feur-character packet 
into @ Long */ 

| Oho for joystick and mouse #/ 
* pocket tine starp #/ 


kstk of0 J* store four byte packet */ 
ketsk etl} = TM NBt ‘p! could be an odd address *7 
kstsk (2) 
kstskcG) = "pF 
ktm = *¢clong *90x084); /* eysten 200h2 clock tick */ 

ey 

ming) 


register struct kbdvease *kbp; 
register void (tx joyvecd(), (*xx nouseverd(); 
register long is, Rt: 


kop = Kedvbase0); 1 keyboard vector table */ 
xx_joyves = kbp->kb_joyvee; J save old joystick vector */ 
Kop >kb_Joyvec = kbd Install new joystick vector */ 
xx nousevee = Kop->kb mousever; /* ditto for mouse */ 
Kp->ke_nousevee = kedvec 

ke = kets; /* initialize state record */ 
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while (Bconseat(8e_cow 


OC /* Tees, until a key 16 struck 


if (ke I= kot-ks) C 2 new event? */ 
ke = KStk 7 then repoct new state... 47 
kt = kee; Pe se. and timestamp *7 


print #(ng0BLx Xun, ks, kt; 


> 


Beonin(8¢_ON); /* clear keystroke */ 
Kop:>kb_jayvee’ = xx_loyweet Pm ARESTORE VECTORS! */ 
Kop:>ke_mousevee = x mousevec; /* OR YOU SOMB ON THE NEXT EVENT! =/ 
return 0; 

> 

See Also 

TOS, xbios 
kbrate—Command 


Reset the keyboard's repeat rate 
Kbrate start. delay 


Kbrate uses the xbios function Kbrate to reset the keyboard's repeat rate. start 
is the amount of time to pass before repeating begins, and de/ay is the time in 
terval between repeats. Both are measured in “system ticks”, each tick being 20 
milliseconds long, For example, the command 

Korate 505 


tells the system thet a key must be held down half a second before repesting 
begins, and then repeating will occur ten times a second thereafter. 


See Also 
commands, TOS 


Kbrate—xhios function 35 (osbind.h) 
Get or set the keyboard’s repeat rate 
#include <osbind.h> 
#include <xbios.h> 
int Kbrate(start. delay) int start, delay; 


Kbrate gets or sets the keyboard's repeat rate. Rates are set as multiples of 
“gystem ticks; each tick is 20 milliseconds long. first sets the number of ticks 
10 wait before a key begins to repeat; delay sets the number of ticks to wait be~ 
tween repeats, If either variable is set to OxFFFF (-1), that value is not 
changed. Kbrate returns an int that holds the previous setting of the keyboard 
rate: the value of firsi is written as the high byte, and the value of delay as the 
low byte. 
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Example 

This example displays the keyboard repeat rate and delay period: it then sets 
them to unreasonable values, lets the user try them out, and finally resets the 
previous values. For an example of using this function from the \auto direc~ 
tory, see the entry for \anto. 

include <osbind.h> 


define DEL 10 
define 


saint) ¢ 
int ole_rate: 
int old-deley: 
chat cj 


old rate = Kbrate(DEL,RT); /* Set the new rate, * 

old-delay = (ola race>>8)20xFF; 

old-rote 8= OxF? 

printf(The repeat delay is 2/50 seconds\n", old delay); 

printf (land repeat rate fs ence every %4/50 seconde\n, 
old rater; 

print#ciRates are changed to del} 


 racerzd\n®, DEL, RI; 


printfo"Try typing scoething--end with “C.\n\n" 
Whilec(e = crawcing) I= N03) ¢ 

Crewfoce)s 
> 


Roratecold deley,old rats 
print#¢ "\nRatas' restored. \n" 9; 


> 


See Also 
TOS, xblos 


keyboard—Definition 


The Alari keyboard is table-driven. The keyboard tables are vectors of byte 
values that are indexed by the scan code passed from the intelligent keyboard 
(KBD). The table is zero-based, so the first entry is always NULL, The 
following display shows the layout of the keyboard, with the scan code each key 
generates being given in hexadecimal: 
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[002906] | 62 181 | 163} 66/6566} 
+ E =| 


petit peste stot el 
for xoys1| 12} 13] 14] 15] 16] 37| 18 19] 14] 1341215315248] 47]167| 68] 6°[ 44] 
|in|1e|1F|20}2% |22|23}26)25)26]27128] 281 ]68]50]40||4A]68)6¢14€ 


[0 |6e|6F 172] 
F | 


i 
| 70 Im | 


Note that the keyboard sold in the United States does not have the key with 
scan code 60, This key is sometimes called the “ISO Key", and is only on 
European models. 


See Also 
ASCH, Keytbl, TOS 


Keytbl—xbios function 16 (osbind.h) 
Set the keyboard’s translation table 
#include <osbind.h> 
#include <xbios.h> 
char *Keytbl(unshifted, shifted, caplock) char *unshifted, shifted. caplocks 


Keytbl sets the keyboard's translation tables. On the Atari ST, each key 
generates three scam codes: one in normal mode, one in. shifted mode, and one 
in caps-lock mode, Each scan code is then translated into an ASCII character 
by being looked up in the apprupriaie table. The variables shifted, unshifted. 
‘and capslock each point to a translation table for the indicated mode; each table 
must be 128 bytes long. Keytbl returns a pointer to the following structure: 


struct keytbl C 
char tunehi fted; 
char tabi fee; 
char *apslock; 


> 


Example 

‘This example prints out the default keyboard map in the form of a C source 
file. This example also demonstrates a good method of obtaining data from the 
Atari's memory. 


Hinetude <osbing.h> 
Hinelude exbioe.n> 
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showap(map, p) 

Feaister enar "map, *p; 

€ 
register ine i, Jp 
printfcvchar X50128 = ¢ Jf 8106Lx +n, map, P): 
for (i= 0; 
putchar'\t!)s 
for 


eB DC 


Hye [[ tee YY) 


PrineFONxE! |, prt B OXFFD; 


puteharc\nt); 
> 
prinetenyz\nt9: 

5 

ein? € 
‘struct Keytbl “1p; 
kp = Keytblcrl, “IL, “1L)5 
shownap("nornal", Kp->kt_normal); 
shoimapC'shifted", kp->kt_ shifted); 
showmaptcapslock', kp->kt_capslock); 
return O; 

> 


See Also 
Bioskeys, TOS, xbios 


keyword—Definition 
‘A keyword is a word that is reserved within C, and may not be used to name 
variables, functions, or macros. The following gives keywords recognized by 
Mark Williams C 


alien entry return 
auto extern short 
break float sizeof 
case for static 
char goto struct, 
continue it ‘switch, 
default int typedef 
do long union 
double readonly unsigned 
else register while 
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The keyword entry is not implemented. The proposed ANSI standard for C 
adds const, signed, and volatile to the above set, and deletes entry and readonly. 
Mark Williams C reserves the keywords readonly and alien, but these ere not 
implemented on the 68000. 


See Also 
C language 


Kgettime—Time function (libe.a/Kgettime) 
Read time from intelligent keyboard's clack 
#include <time.h> 
tm_t *Kgettime(); 


Kgettime is a function that reads the time from the intelligent keyboard's clock. 
Note that this clock is maintained apart from the other clocks on the Atari ST. 
Kgettime returns a pointer to the structure tm_t, which it initializes. tm_t is 
defined in the header file time.h; for more information about it, see the entry 
for time. 


See Also 
Ksettime, time, time.h 


Notes 
Unlike the function Gettime, which deals in two-second increments, Kgettime 
allows the programmer to work with clock ticks. 


Command 
Force TOS to reread the disk cache 
kick drive 


kick forces 10S to read a disk cache. drive is the name of the disk drive whose 


cache is to be read. kick should be used when disks are switched in a drive, to 
ensure that TOS has the correct form of the disk’s root directory in memory. 


See Also 
commands, TOS, 


Ksettime—Time function (libe.a/Ksettime) 
Set time in intelligent keyboard's clock 
include <time.h> 
t Ksettime(sime) tm_t time; 


Ksettime is a function that sets the time on the intelligent keyboard's clock. 
Note that this clock is maintained apart from the other clocks on the Ateri ST. 
time points to 4 copy of the structure tm_t, which is filled by the functions 
gmtime or localtime, This structure is defined in the header file time.h; for 
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more information about it, see the entry for time. 
See Also 

Kgettime, time, timesh 

Noles 


Unlike the function Settime, which deals with two-second increments, Ksettime 
works directly with clock ticks. 
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Iealloc—General function (Iibe.a/Iealtoc) 
Allocate dynamic memory 
char *lealloe(count, size) 
unsigned long count, size; 


Iealloc is one of a set of routines that helps you to manage the computer's free 
memory, or arena. lealloe calls Imalloc to obtain a block large enough to con 
tain cout items of size bytes each; it then initializes the block to zeroes and 
returns a pointer to it. Dynamic memory that is no longer needed can be 
returned to the free memory pool with the function free, 


Unlike the related function calloc, Iealloc takes arguments that are unsigned 
longs; therefore, it can allocate memory blocks that are larger than 64 kilobytes. 


See Also 
arena, callac, free, Imalloe, Irealloe, malloc, notmem, realloc 


Diagnosties 
lealloc returns NULL if insufficient memory is available 


1d—Command 
Link relocatable object files 
1d [option ...] file. 


‘A compiler translates a file of source code into a relocatable object. This 
relocatable object cannot be executed by itself, for calls to routines stored in 
Hbraries have not yet been resolved, Id combines, or links, relocatable object 
files with libraries produced by the archiver ar to construct an executable file. 
For this reason, Id is sometimes called a linker, a link editor, or a loader. 


Id scans its arguments in order and interprets each option as described below, 
Each non-option argument is either a relocatable object file, produced by ce, 
as, or Id, of a library archive produced by ar. It rejects all other arguments and 
prints a diagnostic message. 


Each relocatable file argument is bound into the output file if its machine type 
matches the machine type of the first file so bound; if it does not, a diagnostic 
message is generated. The symbol table of the file is merged into the output 
symbal table and the list of defined and undefined symbols updated ap- 
propriately, If the file redefines a symbol defined in an earlier bound module, 
the redefinition is reported and the link continues. The last such redefinition 
determines the value that the symbol will have in the output file, which may be 
acceptable but is probably an error. 


Each library archive argument is searched only to resolve undefined references, 
ive., if there are no undefined symbols, the linker goes to the next argument im- 
mediately. The kbrary is searched from first module to last and any module 
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that resolves one or more undefined symbols is bound into the output exactly as 
an explicitly named relocatable file is bound. The library is searched repeatedly 
until an entire scan adds nothing to the executable file. 


The order of modules in a library is important in two respects: it will affect the 
time required to search the library, and, if more than one module resolves an 
undefined symbol, it can alter the set of library modules bound into the output. 


A library will link faster if the undefined symbols in any given library module 
are resolved by a library module that comes later in the library. Thus, the lew- 
level library modules, those with no undefined symbols, should come at the end 
of the library, whereas the higher-level modules, those with many undefined 
symbols, should come at the beginning, The library module ranlib.sym, which 
is maintained by the ar s modifier, provides Id with a compressed index to the 
symbols defined in the library. But even with the index, the library will link 
much faster if the modules occur in top-down rather than bottom-up order. 


A library can be constructed to provide a type of “conditional” linking if alter- 
nate resolutions of undefined symbols are archived in a carefully thought-out 
carder. For instance, libe.a contains the modules 


in precisely the order given, though some other modules may intervene. fivit.o 
Contains most of the internals of the STDIO library, exit.o contains the exit() 
function, and _finish.o contains an empty version of _finish(), the function 
that exit() calls to close STDIO streams before process termination. If a 
program uses any STDIO routines, macros, or data, then finit.o will be bound 
into the output with its version of finish(), If a program uses no STDIO, then 
the “dummy” finish.o will be bound into the output because it is the first 
module that defines _finish() that the linker encounters after exit.o adds the 
undefined reference. This saves approximately 3,000 bytes, To set the order of 
routines within a library, use the archiver ar; this, of course, has its own entry 
in the Lexicon. 


The available options are as follows: 


-d Define common regions even if relocation information is retained. By 
default, Id leaves common areas undefined if there are undefined symbols 
or if the -r option is specified, 

-kfilename 
Link with the object file filename. This option is used to link programs to 
access code or data at fixed locations outside the program being linked, 


such as a library burned into a ROM or the fixed low memory locations 
documented by Atari. 
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=I name 
"An abbreviation for the libraries named in the environmental variable 
LIBPATH. Id searches each directory named in LIBPATH for a file 
named libname.a. 


-0 file 
Write output to file (default, L.prg.) 

-R value 
Relocation base option. By default, ld links executeable files to run at the 
user-base for the computer, In almost all cases, the user-hase is zero. If 
the -R option is used, Id will link the executeable to run at value instead 
of at zero, value can be set to any C-style constant, or to a symbol name 
that Id can find in the object files and archives being linked; remember 
that a C-accessible symbol must end with an underscore character * 
‘This option is used primarily to produce output files that can be burned 
into ROM. These programs must make their own provisions for 
relocating initialized data and other tasks, 


Retain relocation information in the output, and issue no diagnostic mes~ 
sage for undefined symbols. Ry default Id discards relocation information 
from the output if there are no undefined symbols. 


Strip the symbol table from the output. The same effect may be obtained 
by using strip. The -s and -r options are mutually exclusive. 


=u symbol 
“add symbol to the symbol table as a global reference, usually to force the 
linking of a particular library module. 


=X Discard local compiler-generated symbols of the form ‘L.... 
=x Discard all local symbols. 


See Also 
ar, as, cc, commands, n.out 


Notes 

If you are linking a program by hand (that'is, running Id independently from 
the cc command), be sure to include the appropriate run-time start-up routine 
with the Id command Line; otherwise, the program will not Tink correctly. 


Idexp—General function (Iibe.a/Idexp) 


Separate mantissa and exponent 
double Idexp(ra, e) double m; int e 


Idexp combines the mantissa m with the binary exponent ¢ to return a floating 
point value real that satisfies the equation real=m*2*e. 
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See Also 
atof, ceil, fabs, floor, frexp, modf 


Lexicon—Introduction 


The Mark Williams Lexicon is a new approach to documentation of computer 
software. The Lexicon has been designed to improve documentation and 
eliminate some limitations found in more conventional documentation, 


How to use the Lexicon 

The Lexicon consists of one large document that contains all entries for every 
aspect of Mark Williams C. You will not have to search through a number of 
different manuals to find the entry you are looking for. 


Every entry in the Lexicon has the seme structure. The first line gives the 
name of the topic being discussed, followed by its type (e.g, Mathematics 
function) and, where appropriate, the file where it is kept. 


The next lines briefly describes the item, then give the item's usage, where 2p- 
plicable, These are followed a brief discussion of the item, and an example. 
Cross-references follow; these can be to other entries or to other texts, notably 
to The Art of Compuer Programming or The C Programming Language. Disg- 
nostics and notes, where applicable, conclude each entry. 

Types of entries 

‘There are several types of entries, as follows: 


Command 
‘Commands or utilities that run directly under the micro-shell msh, or 
from the GEM desktop. 


Library functions 
Functions or mucros that are included with Mack Williams C; these in- 
clude the following: ctype macros (a macro that checks the type of data 
being handled); debugging macros; general functious (non-specialized C 
functions and macros); mathemati¢s functions; STDIO functions; STDIO 
macros; string functions (routines used to manipulate character strings); 
and time functions (routines used to manipulate the time setting rendeced 
by TOS). 

Definition 
‘These entries define technical terms and provide backround information 
that is useful in C programming 


Overview 
Give an overview of a group of routines. 
‘Symbols and constants 


Data elements that are used while compiling or running programs; these 
include environmental parameters, linker-defined symbols, and manifest 
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constants, 


‘TOS support 

Entries that give information useful in programming for the Atari ST; 
‘these include the following: TOS devices (logical devices used by TOS to 
describe its peripheral devices; TOS functions; and TOS’ support 
(routines designed to support the TOS operating system). 


UNIX routines 
‘A function, macro, or data item included to provide compatibility with 
UNIX, COHERENT, and related operating systems. 


The Overview entries review an entire topic, and give full cross-references to all 
of the entries that belong to the category discussed. If you are unfamiliar with 
a particular variety of routine, be sure to check the Overview entry that discus- 
ses it. The following Overview entries are included in the Lexicon: 


C tanguage 
commands 

ctype 
declarations 

TOS functions 
UNIX system calls 


Use the Lexicon 

If, while reading an entry, you encounter a technical term that you do not un- 
derstand, be sure to look it up in the Lexicon. You should find an entry for it. 
For example, if a function is said to return a data type float and you do not 
know exactly whata float is, look it up. You will find it described in full, In 
this way, you should increase your understanding of Mark Williams C, and so 
‘make your programming easier and more productive. 


We wish to hear your comments on the Lexicon; we especially wish to hear if 
you discover something wrong or if an entry that you looked for is missing. 


libaes.a—Definition 
libaes.a is the library that holds the GEM AES binding routines. AES stands 
for application environment services: the routines contained in libaes.a allow you 
to invoke the elements of the GEM graphics interface, such as icons, windows, 
and pull-down menus. See the entry for AES for a brief description of the 
routines in this library, 


To alter libaes.a or print out its table of contents, use the archiver ar. 


This library can be called on the ce command fine in one of two ways. First, 
the - VGEM will automatically link it in, plus the library libydi.a and the run- 
time startup module ertsg.o, Second, it can be included by itself with the library 
option -laes; note that this option must come at the end of the cc command line, 
of the library will not be linked i 
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Example 

Far an example of a program that uses libaes.a, s0e the ontry for AES. 
See Also 

AES, ar, crtsg.o, gemdefs.h, library, nm, TOS, vdibind.h 


libe.a—Definition 
libe.a is the archive file that holds the more commonly used C functions, system 
calls, and compiler run-time support routines. See the entries for string, 
STDIO, and UNIX routines for information about many of the routines within 
libea, For a complete listing of the modules within libe.a, pass the following 
command to msh; 


ar t Libe.a >foo 
‘This writes a list of the library's contents into the file foo. 


See Also 
ar, library, am 


libm.a is the archive file that holds the mathemati 


See Also 
ar, library, mathematics library, math.h, om 


library 


LIBPATH—Environmental parameter 
LIBPATH names the directories that c¢ searches for the compiler’s executable 
programs and libraries, make also searches these directories for the files 
mmacros and mactions, and Id looks them for its libraries. For example, the 
command 


setenv LISPATH 


eALib, ,be\LID 


tells ce to look for the compiler’s executable files first in directory lib on drive 
A; then in the current directory (as indicated by the two commas with nothing 
between them), and finally in lib on drive B:. 


It is set with the seteny command. 


See Also 
msh, seteny 


library—Definition 
‘A library is an archive file of commonly used functions that have been com- 
piled, tested, and stored for inclusion in a program at link time, Normally, C 
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line feed—Defin: 


uses two libraries: libe.a, which holds most standard C functions, such as 1/0 
function; and libm.a, which holds mathematical functions. Users, however, 
may create their own libraries of functions or purchase such libraries from else- 
where, Mark Williams C includes an archiver that allows you to create custom 
libraries. 


The files in a library can be listed with ar; the sizes of the files can be listed 
with size; the symbol tables of the object files may be listed with nm. 


See Also 
ar, function, 


tbaes.a, libe.a, libm.a, Ubydi.a 


Definition 

libydi.a is the library that holds the GEM VDI routines. VDI stands for virtual 
device interface. These routines perform low-level GEM graphics tasks, and 
are kept in the library libvdi.a. For a brief summary of the routines in this 
library, see the entry for VDI. 


libydi.a's table of contents can be printed out with the command am, and its 
contents can be altered with the archiver ar. 


This library can be called on the ce command line in one of two ways, First, 
the -VGEM will automatically link it in, plus the library libaes.a and the run- 
time startup module ertsg.o, Second, it can be included by itself with the library 
option -lydi; note that this option must come at the evd of the ce command line, 
or the library will not be linked in. 


See Also 
AES, ar, ertsg.o, gemdefs.h, library, am, TOS, ydibind.n 


‘Mark Williams C recognizes the literal character *\n' for the ASCII line feed 
charecter LF (octal 013), This character may be used as a character constant or 
in a string constant, like the other character constants: ‘\z', which rings the 
audible bell on the terminal; *\b’, to backspace; *\f", to passa formfeed com- 
mand 1 the printer; ‘\r, for a carriage reiurn; *\t", for a horizontal tab charac- 
ter; and ‘\v', for a vertical tab character. 


See Also 
ASCII 


Notes 

On many systems, \n both feeds the line and tosses the carriage; however, on 
the Atari ST \n must be used with \r if the program does not work through 
STDIO. 
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Line A~Definition 
Line A is the interface to the Atari ST's assembly-language-level graphics 
routines. 


If the machine instructions of the 68000 are sorted by their bit patterns, they 
may be categorized into 16 “lines”, according to the value of the high nybble of 
the instruction word, Lines 1, 2, and 3, for instance, give the move instructions, 
Lines A and F are not used by the 68000 instruction set, so the processor traps 
when it encountors instructions ial bit patterns. Line F is used by 
the Atari ROM to make GEM AES and VDI fit into the ROM. Line A is used 
to call the low-level graphics routines. 


Each Line A function consists of few lines of assembly language, which save 
registers, load parameters, execute one of the unimplemented Line A instruc~ 
tions, restore registers, and return. These perform simple graphics functions, 
such as drawing lines, displaying characters, or drawing polygons. They under- 
pin the GEM VDI routines. 


Most functions pass their parameters through the structure la_data. Ia_data is 
referenced through pointer in in the structure la_init, which is initisTized by 
function linea. The exceptions are linea?, which takes the structure la_blit; 
lineac, which takes a pointer: and linead, which takes two pointers. All 
functions and structures are declared in the header file linea.h, which also con 
tains a number of macros used to access elements within the Line A structures. 


‘The following briefly summarizes the Line A functions 


Initialize 
Put pixel 

Get pixel 

Draw a line 

Draw a horizontal fine 
Draw a filled rectangle 
Draw a filled polygon 


Bit blit 
Text blit 
Show the mouse’s pointer 
Hide the mouse’s pointer 
lineab Transform the mouse's pointer 
Tineac Erase a sprite 
linead Draw a sprite 
Tineae Copy a raster form 
lineat Seedfill 1 
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Examples 

‘The first example demonstrates linea3, lineaS, and linea8, When compiled, it 
takes four arguments, in decimal: an ASCII character; a column number (0 
through 79); a row number (0 through 23); and a made umber (0 through 63). 
‘The mode indicates how the character named in the first argument is displayed, 


Hinclude <stdio.h> 
Hinelude <Linea.h> 


struct Lafont “fontp: /* font pointer for Linea interface */ 
char Linett001, #p; 

char ser wrkti0240 J? area for grathics */ « 
fnt.ser_fat, ser_ehi; /* length and disp for undertine */ 

* put @ character on the sereen. 

“” 


putserce, x, ¥, mode) 
J character to put out */ 

Y* 8 y coordinates on 80425 screen */ 

7 see vst_etfects for List of codes */ 


unsigned int trp: 
static long parma 


1 


tap = © - fontp->font_lov_ede; 
DELX = fontp->font_char_off tmpel] = 

(SR0X = fontp->fant_char_of Ctmp}); 
Dstk = x ce: 


Dsty = y << 4 


J? replace ode */ 


iFemode & 8 € iP reverse */ 
X2 = (X) = DST) + ser fats 
¥2 = (YI = DSIY) + scr_chi} 
PATPIR © Spatnck; 


PATHSK 
cue 

Hineas (/* Filled rectangle */ 
Waco = 2 0° node */ 
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iftmode & 16) ¢ (f wedertine */ 
XZ = CK) = STAD + ser fats 
yO = Yt = pst + ser cht; 
Unease: 
LUNAS =~ 
WoOE = 2; 
Uinea3cie 


> 
else 
Linea 
> 


f Infeialize matertel for screen */ 


init sero € 
inea0(¢ ( initialize Linea */ 
ineasc: 7 bide mouse */ 
fonep = la_init-ti_at (2; 2 x16 system font */ 


FBASE = fontp:>font_ da 
FAIDTH = fontp->fant_widt 
TexTFG = 1; /* text forground white */ 
sRcY = 0; 

DELY = fontp->font_hetght; 
ser_fat = fontp->font_fatest; 
ser_chi = fontp->font height ~ 


couaiTo = 
coustTt 
cousire 
‘cOLEITS = 0; 
Livesk = 035555; 
SKEMISK = OXTTT17 
SCRTCHP = ger_wrky 
verceT 
UsTLIN 

> | 


infe_msgt 
printé(*\0S3EFrogren te denonstrate sone Lines capabilitfes\n"); 
printf(Each line should have four decimal nunbers or ‘quit"\n"); 
Drintf(t'The AMCIT value of the cher 'At==65, etc.\n"); 
Brintf("The x and y coordinates relative to’a 25X80 screen\n"); 
rintf ("The made Tzthicken 2-grey 4=itelie\n'); 
printf Bereverse 16eurderline\n"); 
print¢(iconbinations work but sone are weird\n\n"); 

> | 


aint) 
int ©, es Ys Op 
initserO? 
inieimea0)? 
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fortzi) 
princFC"\OB3A\OSBK> "5 
‘lush(stdout); 
gets(Line): 
HCistremptline, quit")? 
returnt0); 
sscant(Ling, id Xa xd te, fe, 8x, By, 8m; 
put serve, & Ye Me 
5 
> 


‘The second example uses lineaS to draw a filled rectangle. Typing any key 
ends the display. 


include <Linea.b> 
Hineiude <osbind.h> 


boxtis 1) 
« 
/* pattern all ones */ 
79 x0r pede */ 
PATPTR = Boater 
PATNSK = 17 Uf sizeof pattern */ 
CLIP = 0; J= 90 clipping */ 
Mate 
==); 
ness; J dea box *7 


Uyneab0>; 
nese): 
Coonws(\OS3E\0354 Any Key stops the disploy"); 


fort;Geonis() == 93) 
Forti = 50; 1 < 200; 1449 
ont, 400-197 


ceoninty; (Jt eat cher */ 
Ceons("\033e\0"9; 


Fy 


See Also 
linea.h, TOS, VDI 


Notes 

Line A is described in chapter 3.4 of Atari ST Internals, and in unpublished 
‘Atari documentation, ‘These functions are extremely complex, and are not 
fhoroughly documented. Programmers who wish to use these routines are well 
havised to use the ebove example as 2 model for testing the Line A functions 
and studying how they manipulate the screen. 
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linea.h—Header file 


finea.h is the header file that declares the the Atari’s Line A routines. It also 
defines all specialized structures used by them. 

See Also 

header file, Line A, TOS 


Imalloc— General Functicn (libe.a/Imalloc) 


Allocate dynamic memory 
char *Imalloe(size) unsigned long si 


Imalloc helps to manage an a program's arena, It uses a circular, first-fit algo- 
rithm to select an unused block of at least size bytes, marks the portion it uses, 
and returns a pointer to it. The function free can be used to return allocated 
memory to the free memory pool. 


Unlike the related function malloc, Imalloe takes an unsigned long as its size 
argument, which allows allocation of memory blocks larger than 64 kilobytes. 
Example 

For an example of a related function, see malloc. 

See Also 

arena, calloc, free, lealloc, Irealloe, malloc, notmem, realloe, setbuf 
Diagnostics 

Imalloc returns NULL if insufficient memory is available, It prints a mesage 
and calls abort if it discovers that the arena has been corrupted, which most of 
ten ocenirs hy storing past the bounds of an allocated black, Imallac will behave 
unpredictably if handed an unreliable per. 


localtime—Time function (libe.a/ctime) 


Convert TOS time to ASCH string 
include <time.h> 

tm_t *localtime(timep) time_t *tim 
tint *localtime(limep) long. 


localtime converts the system's internal time into the form deseri 
structure tm_t. 


ved in the 


timep points to the system time, It is declated to be of type time_t, which is 
defined in the header file time.h as being equivalent to 2 long. The system time, 
in turn, is returned by the function time. Mark Williams C defines the system 
Ume seconds since midnight January 1, 1970 0h0Om00s GMT. 
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localtime returns a pointer to the structure, tm_t, which is also defined in 

time,h. tm_t breaks the system time down into integer years since 1900, the 

month, day of the month, the hour, the minute, the second, the day of the 

week, and yearday, The function asctime turns tm_t into an ASCIT string that 
rn be read by humans. 


Unlike its cousin gmtime, localtime returns the local time, including conversion 
to daylight saving time, if applicable. The daylight saving time flag indicates 
whether daylight saving time is now in effect, not whether it is in effect during 
some part of the year. Note, too, that the time zone is set by localtime every 
time the value returned by 

setenv IREZOME") 
changes. 


Example 
For an example of how to use this function, see the entry for asetime. 


See Also 
gmtime, time, TIMEZONE 
Notes 


ocaltime returns a pointer to a statically allocated data area that is overwritten 
by successive calls. 


log—Mathematics function (libm.a/log) 
Compute natural logarithm 
#include <math.h> 
double log(=) double 3 


Jog returns the natural (base e) logarithm of its argument z. 
Example 

For an example of this function, see the entry for exp. 

See Also 

logi0, mathematics library 

Diagnostics 


‘A domain error in log (z is less than or equal to 0) sets errno to EDOM and 
returns 0. 


log10—Mathematics function (libm.a/log10) 
‘Compute common logarithm 
#include <math.h> 
double logi0(=) double 
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Togi0 returns the common (base 10) logarithm of its argument z, 
Example 

For an example of this function, see the entry for exp. 

See Also 

log, mathematics library 

Diagnostics 


A domain error in logl0 (z is less than or equal to 0) sets errno to EDOM and 
returns 0, 


Logbsse—xbios function 3 (osbind.h) 


298 


Read the logical sereen’s display base 
#include <osbind.h> 

#include <xbios.h> 

long Logbase() 


Logbase reads the screen's logical display base, and returns a pointer to it, 


‘The logical base is where the screen-drawing primitives do their work, This is 
in contrast to the physical base, which ig returned by Physbase; the latter is 
where the display hardware gets the image that is displayed on’ the monitor. 
This differentiation allows you to draw one pattern while displaying another. 


Example 
This example gets the logical and physical screen base addresses. If they are the 
same, it fills the top of the screen with the pattern 10101010; otherwise, it 
prints out cach address. In the case of this program, they will generally be 
equal. 


#inetude “oebind he 


tained € 
long Abas 
long *pbase; 
Sint x; 
Usase = Cong #) Lashasacs J Got Logizal seroen *, 
poase = (long *) PhysbeseO; 7* Get physical screen */ 
i fcpeese == Ibese) £ 
forexet 
9 alse ¢ 
printfivThe logteat sereen is at £Lx\nt, lbase), 
printfo"The physiesl sereen is ot XIx\n", base); 
9 
exitor 


Mark Williams C 


Lexicon long-Irealloc 


See Also 
Physbase, TOS, xbios 


long—Definition 
‘A long is a numeric data type, By definition, a long is the largest integer data 
type; it cannot be smaller than an int, although on some machines an int ond a 
long’ will be the same size. On most machines, sizeof long will equal two 
machine words, or four chars (31 data bits plus a sign bit). 


See Also 
declarations, int 


longjmp—General function (libe.a/setimp) 
Return from a non-local goto 
#include <setjmp.h> 
longimp(eny, real) jmp_buf en; int real 


The function call is the only mechanism that C provides to transfer control be~ 
tween functions, This mechanism is inadequate for some purposes, such as 
handling unexpected errors or interrupts at lower levels of a program, To 
answer this need, longjmp helps to provide a non-local goto facility. 


Jongjmp restores an environment that had been saved by a previous set}mp call, 
and returns value rval to the caller of setjmp, just as if the set}mp call had just 
returned. longjmp must not restore the environment of a routine that hes al- 
ready returned, The type declaration for jmp_buf is in the header file 
sejmp.h, The environment saved includes the program counter, stack pointer, 
and stack frame, ‘These routines do not restore register variables in the en- 
vironment returned. 


See Also 

setimp, setimp-h 

Notes 

Programmers should note that many user-level routines cannot be interrupted 
and reentered safely, For that reason, improper use of longjmp and setjmp will 
result in the creation of mysterious and irreproducible bugs. Do not attempt to 
use Iongjmp within an exception handler. 


Irealloe—General function (libe.a/Irealloc) 
Reallocate dynamic memory 
char “Irealloe(pir, size) 
char *pir; unsigned long si: 


Irealloc helps to manage a program's arena, It returns a block of size bytes that 
holds the contents of the old block, up to the smaller of the old and new sizes. 
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Irealloc tries to return the same block, truncated or extended; if size is smaller 
than the size of the old block, Irealloe will return the same pir, 

Unlike the related function realloc, Irealloc takes an unsigned long as its 
argument, and therefore can reallocate a memory blocks that is larger than 64 
kilobytes, 


See Also 
arena, calloc, free, Iealloc, Imalloc, malloc, notmem, realloc, setbuf 


Diagnostics 

Irealloe recurns NULL if insufficient memory is available. Tt prints « message 
and calls abort if it discovers that the arena has been corrupted, which most of 
ten occurs by storing past the bounds of an allocated block, Irealloc will behave 
capriciously if handed a fallacious ptr. 


Is—Command 
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List directory contents 

Isl-adirt] [file] 

Is prints information about each file, Normally, Is sorts by file name and prints 
only the name of each file. If a directory name is given as an argument, Is sorts 
and lists its contents, not including *' and ‘..". If no file is named, Is lists the 
contents of the current directory. 


The following options control how Is sorts and displays its output. 
a Print all directory entries, including *, *.", any hidden files, and volume 
ID's. 
-d Treat directories as if they were files, 


<1 Print information in long format, The fields give mode bits, size in byles, 
date of last update, and file name. 


1 Reverse the sense of the sort. 
-t Sort by time, newest first, 


The mode field in the long list format consists of four characters, The first 
character will be one of the following: 


- regular file 
d directory 

s system file 

y volume identifier 


‘The next two characters are r or - if the file is read-only, and w if the file can 
be written to. The fourth character is h if the file is hidden, 
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See Also 
commands, msh 


Iseek—UNIX system call (libe.a/Iseek) 


ttom- 


Set read/write posi 
long Iseck(/d, where, how) 
int fd, how; long where; 


Iseek changes the location where the next read or write operation occurs within 
the file identified by file descriptor fd. Each read or write procedure executes 
‘at the current seek position, and advances the seek position by the number of 
bytes successfully transferred. The where and how arguments specify the 
desired seek position, where indicates the new seck position in the file; it is 
measured from the beginning of the file if how is zero, from the current seek 
position if Aow is one, or from the end of the file if how is two. A successful 
call to Iseek returns the new seek position. 


See Also 
SIDIO, UNIX routines 


Diagnostics 
Iseek returns (long)-1 on an error, such as seeking to negative position, 


Notes 

For any diagnostic error, Iseek returns -1; otherwise, it returns 0, Note that if 
Iseek goes beyond the end of the file, it will not return an error message until 
the corresponding read or write is performed. 


Command 
‘Redraw the screen from low to medium resolution 
ltom 


Itom redraws the screen, moving from low to medium resotution, 


See Also 
commands, htom, mtoh, mtol, TOS 


Ivalue—Definition 


Mar! 


‘An Ivalue is an expression that designates a region of storage. The name comes 
from the assignment expression el=e2;, in which the left operand must be an 
Wwalue. 


An identifier has both an [value (its address) and an rvalue (its contents). Some 
C operators reauire Ivalue operands; the left operand of an assignment must be 
‘an Ivalue. Some operators give Ivalue results; if ¢ is a pointer expression, *e is 
‘an ivalue that designates the object to which e points, The following example 
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shows the use of both an Ivalue and a rvalue: 
int 6, “py 
/f ip is an lvalue, i and 81 are rvatues */ 
7 isan Walue, 3 1s en rvalue */ 
7 tip is an Ivalue, 4 is an rvalue */ 
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macro-Definition 
‘A macro is a collection of instructions that is given a name and can be 
referenced in a program. For example, getchar() is a macro that consists of the 
Fonction call gete(stdin), Note that because macros may employ an argument 
times, any arguments that have side effects will have the side effect repeated 
times as well, which may be undesirable. 


See Also 
Tunetion 


main—Definition 
‘A C program consists of a set of functions, one of which must be called main. 
‘This function is called from the runtime startoff after the runtime environment 
has been initialized. 


Programs can terminate in one of two ways. The easiest is simply to have the 
main routine return, Control is passed back 10. the run-time start-up code, 
which performs cleatup operations and then returns control to the operating 
system, passing the returned value from main as eait status. Tn some situations 
(errors, for example), it may be necessary to stop @ program, and you may not 
want (or even be able) to return to the main routine, Here, the exit routine can 
be used; it cleans up the debris left by the broken program and returas control 
to the operating system. 


A second exit routine, called _exit, quickly retums control to the operating 
system without performing any Cleanup. This routine should be used with care, 
bacause bypassing the cleanup will leave files open and buffers of data in 
memory. 


Programs compiled by Mark Williams C return to the program that called them; 
if they return from main with a value or call exit with @ value, thet value is 
returned to their caller. Programs that invoke other programs through the sys- 
tem, execve, or Pexec functions check the returned value to see if these secon- 
dary programs terminated successfully, 

See Also 

farge, argy, enyp, exit, exit, runtime startup 


make—Command 
Program building discipline 
make [option ...J largument ... [target . 


make assists in building programs from more than one compilable module, 


Complex programs are often constructed of several object modules, which are 
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the product of compiling source programs. Source programs may refer to 
include files, which are subject to independent change. Reeompiling and 
relinking complicated programs correctly can be difficult and tedious. 


make regenerates a program, based upon a specification of the structure of the 
program in makefile and the modification times of the files involved; make will 
recompile a source file only if it is younger than the object module. 


makefile has three types of lines: macro definitions, dependency definitions, and 
conimands. Macro definitions contain the equal sign '="; dependency definitions 
have a target name at the beginning of a line followed by a colon: and command 
lines begin with a space or tab, Comments within lines begin with an unqucted 
pound sign ‘#’, and end at the end of the line. Long non-comment lines may be 
broken with a quoted newline character. If no target is given on the command 
Jing, make assumes the target to be the first target in makefile. 


Dependencies 

makefile specifies which files depend upon other files, and how to recreate the 
dependent files, Each targer Tile is followed by a colon, followed by a space- 
separated list of files upon which it depends. The commands to recreate the 
dependent file are on the following lines, each beginning with a tab or space. If 
the target file test.o depends upon the source file test.c, the dependency is 
illustrated by 


tests testo 
co -0 teste -0 test 


Tf test.c is modified or recreated, make will issue the ce command to regenerate 
the dependent file test.o. 


make knows about common dependencies, ¢.g., that .0 files depend upon .c files 
with the same base name. The target SUFFIXES contains the suffixes make 
knows about. make also has a set of rules to regenerate dependent files. For 
example, for a sourve file with suffix .c and dependent file suffix .0, the target 
.c.0 gives the regeneration rule: 


co 0-86 


Here $< stands for the name of the file that causes the action. The default suf- 
fixes and rules are kept in the files mmacros and mactions, which should be 
Kept in one of the directories named in the LIBPATH environmental variable. 
‘The dependencies can be changed by editing these files, 


‘acros 

To simplify the writing of complex dependencies, make provides a macro 
facility, To define a macro, write 

NAME = string 


‘The string is terminated by the end-of-line character, so it can contain blanks. 
To refer to the value of the macro, use a dollar siga ‘S’ followed by the macro 
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name enclosed in parentheses: 
S(VAME) 


If the macro name is one character, parentheses are not necessary, make uses 
macros in the definition of default rules: 


coo) (CFLAGS) -c $< 


where the macros are defined as 


comes 
ccrLagse-o 


Other built-in macros used in interpretation of rules are: 
$* target name less suffix 
S@ target name 
$< list of referred files 
$2 referred files newer than target, 
Each command tine argument should be a macro definition of the form 
OBJECT=a.0 bo 


Arguments that include spaces must be surrounded by quotation marks, because 
blanks are significant to the micro-shell msh. 


Options 
‘The following lists the options that can be passed to make on its command line. 


-d (Debug) Give verbose printout of all decisions and information going into 
decisions. 


+f file 
‘file contains the make specification. If this option does not appear, make 
uses the file makefile or Makefile in the current directory. 


i Ignore error returns from commands and continue processing, Normally, 
make exits if commands return error status. 


-n Test only; suppresses actual execution of commands. 
=p Print all macro definitions and target descriptions. 


-q Return a zero exit status if the targets are up to date. No commands are 
executed, 


1 Do not use built-in rules descr 


ing dependencies. 


-s Do not print command lines when executing them. Commands preceded 
‘by “@" are not printed, except under the -m option. 
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(Touch option) Force the dates of targets to be the current time, and 
bypass actual regeneration. 


Invoking make 
make can be used either from the micra-shell msh, or from the TOS desktop. 


To use make from the TOS desktop, its suffix must be changed to TOS or TTP. 
Once this is done, you can invoke make simply pointing to the appropriate icon 
with your mouse end clicking it, When the Open Application box appears, 
enter the options and target you want. make reads whatever makelile is in the 
current directory, and executes its instructions, It cannot accept options from 
the desktop, however. 


If you wish to use make from msh, simply invoke msh from TOS, then enter the 
make command as you normally would, including options and a path name for 
the makefile, should it be in a directory other than one that you have 
previously defined in the PATH environmental parameter. 


See Also 
commands, msh 

See the tutorial Building Programs with Make, which is included at the cad of 
this manwal, 


Diagnostics 

make reports its exit status if interrupted or if an executed command returns 
error status. It replies “Target name not defined" or “Don't know how to make 
target name” if it cannot find appropriate rules. 


Notes 

Note that the order of items in mmactos/.SUFFIXES matters. The consequent 
of a default rule (€.g,, .obj) must precede the antecedent (e.g, .c) in the entry 
SUFFIXES. Otherwise, make will not work properly. 
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Allocate dynamic memory 
char *malloc(size) unsigned size; 


malloc helps to manage an a program's arena, Tt uses a circular, first-fit algo- 
sithm to select an unused block of at least size bytes, marks the portion it uses, 
and returns 4 pointer to it, The function free can be used to return allocated 
memory to the free memory pool, 


Example 

‘This example reads from the standard input up to N/TEMS items, each of 
which is up to MAXLEN long, sorts them, and writes the sorted list onto the 
standard output, It demonstrates the functions qsort, malloc, free, exit, and 
stremp. You may want to use as input what the example for Random has output. 
For an example of how to use malloc in a TOS application, see the entry for 
Fgetdta, 
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Hinetude <stdio.h> 
fidefine wiTeNs 512 
fidefine NAXLEN 256 
char data (NITEM 
char string IMAXLEN 


main) « 
register char **epp; 
register int count; 
extern int compart); 
extern char taal Lact 
extern char *gets( 


for (ep = tdatat03; cpp < ddatatNITEMS); eppte) € 
{f (gete(string) == MULL) 
‘breah 
HF «Cropp = mat loccstrlenstring) + 19) == NULL) 
exit); 
stresy(tepp, string); 


> 

count = op ~ Bdatacor; 

‘gsort(data, count, sizeof(char *), compare); 

for Cepp = Adata tO) eteount]; ppt) 
rinc#C"%s\n, *epp); 
Freet*epp); 


> 
exit000; 
> 
comparecpl, 72) 
register cher ™pl, **p2; 
€ 
extern int stream): 
return(strenp(*pl, "p29; 
> 
See Also 
arena, calloc, free, Icalloc, Imalloe, Irealloc, notmem, realloc, setbuf 


Diagnostics 

malloc returns NULL if insufficient memory is available. It prints a message 
and calls abort if it discovers that the arena has been corrupted, which most of 
ten occurs by storing past the bounds of an allocated black. 


The related function Imalloc takes an unsigned long as its size argument, and 
therefore can allocate memory blocks that are larger than 64 kilobytes. 


Malloc—gemdos function 72 (osbind,h) 
Allocate dynamic memory 
#include <osbind.h> 
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tong Malloe() long m 

Malloc allocates dynamic memory. n contains either the number of bytes to be 
allocated, or the number -IL (0xFFFFFFFF), which returns all available 
memory. If m contains the number of bytes to be allocated, Malloe returns a 
pointer to the starting address of the memory allocated: if m contains -IL., then 
Malloc returns the number of bytes available; in either cese, Malloc returns 0 
upon failure. 

Example 

This program displays the amount of free memory available. 


include <osbind.h> 


main) 
« 


printtcrpild bytes of menary frael\n¥, Maltoc(-1L)); 


> 


See Also 
gemdos, Mfree, Mshrink, TOS 


Notes 

As of this writing, Malloe appears to have some peculiarities. Always Malloe 
even-size blocks of memory. Always Mfree memory in the reverse order of 
allocation. Finally, try to Malloe a few pieces of memory; there appears to be 
an undocumented limit on the number of times Malloc can be called by.a given 
program, ‘Though large, this number is Finite; when it is exceeded, Malloc will 
return NULL even though considerable amounts of memory are still available. 


manifest constant—Definition 
A manifest constant is a numeric constant that ig referenced by a symbolic 
name, to allow it to be defined differently under different computing environ- 
ments, An example is EOF, the end-of-file marker, which has wildly different 
representations under different operating systems. 


‘The use of manifest constants in programs help to ensure that code is portable, 
a single header file, where they 


See Also 
EOF, header file, NULL, portability 


mantissa—Definition 
In mathematics, a mantissa is the fractional part of a logarithm, In the context 
of C, “mantissa” refers to the fractional portion of a floating point number. 
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math, 


See Also 
data formats, double, float, frexp 


h—Header file 
Header file for mathematics functions 
#include <math.h> 


math.h is the header file to be included with programs that use any of Mark 
Williams C's mathematics routines. It includes the following: definitions for 
mathematical functions; error return values, as used by the errao function; 
definitions of mathematical constants, e.g., Pl; the definition of structure epx, 
which describes complex variables, definitions of internal compiler functions, 
and, finally, declarations of mathematical functions. 


See Also 
m.a, mathematics library 


mathematics library—Overview 


‘The following mathematics routines are available with Mark Williams C: 


acos inverse cosine 

asin inverse sine 

atan inverse tangent 

atan2 inverse tangent of quotient 
cabs complex absolute value 
cos cosine 

cosh hyperbolic cosine 


exponent 
absolute value function 
floor function 
hypotenuse 

Bessel function, order 0 
Bessel function, order 1 
Bessel function, order 
natural logarithm 
common logarithm 
power 

sine 

hyperbolic sine 

square root 

tangent 

hyperbolic tangent 
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See Also 
libm.a, Lexicon, math. 


Noies 

When programs that contain mathematics routines are compiled, the mathe- 
matics libraries must be called specifically on the ce command line. For ex- 
ample, to compile the example presenied under the entry for acos, use the 
Following ee command fine: 


0 +f +0 aces.pra.nces.c -Im 


‘The =f option links in the floating point routines for primif, while the -Im op- 
tion links in the mathematics libraries. Note that the -Im option must come csi 
onthe ce command line, or the library will not be searched properly 


me—Command 
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Invoke MicroEMACS screen editor 
me [=e] [file 1 


me is the command that invokes MicroOEMACS, Mark Williams C’s soreen 
editor. With it, the user can insert text, delete text, move text, search for a 
string and replace it, and perform many other editing tasks. MicroEMAC: 
reads text from files and writes edited text to files; it can edit several files 
simultaneously. 


If the command me is used without arguments, MicroEMACS opens an empty 
buffer. If used with one or more file name arguments, MicroBMACS will to 
open each of the files named, and display its.contents in a window. If a file 
cannot be found, MicroEMACS will assume that you are creating it for the first 
time, and create an appropriately named buffer and file descriptor for it 


‘The last line of the soreen is used to print messages and inquiries, The rest of 
the screen is portioned into one or more windows in which text is displayed 
‘The last line of each window shows whether the text has been changed, the 
ame of the buffer, and the name of the file associated with the window. 
MicroEMACS notes its current position and displays a cursor under the charac~ 
ter to the right of that position, It remembers a position called the mark. Some 
commands manipulate the block of text between the current position and the 
mark, 


The printable ASCII characters, from *’ to '~*, can be inserted at the current 
position. Control characters and escape sequences are recognized as commands, 
described below. A command character can be inserted into the text by 
prefixing it with <ctrl-Q>. 

Commands remove text in two different ways. Delete commands remove text 
and throw it away, whereas Ail/ commands remove text but save it in the kill 
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buffer. Successive kill commands append text to the previous kill buffer. 


Search commands prompt for a search string terminated by <RETURN> and 
then search for it, Case sensitivity for searching can be toggled with the com- 
mand <ese>@. ‘Typing <RETURN> instead of a search string tells 
MicroEMACS to use the previous search string, 


Some commands manipulate words rather than characters; a word consists of 
upper-case and lower-case letters, '_', and ‘S'. Usually, a character command 
ig a control character and the corréiponding word command is an escape se- 
quence, For example, <ctri-F> moves forward one character and <esc>F moves 
forward one word. Note that the MicroEMACS commands are not case sen 
; for example, <etrl-F> and <etrl-f> are identical. 


MicroEMACS can be invoked automatically by the compiler command ce to 
display for correction any errors that occurred during compilation. The -A op- 
tion to ce will cause MicroEMACS to be invoked with error messages in one 
window, source code in the other, and with the cursor fixed at the line on 
which the first error occurred. When the text is altered, exiting from 
MicroEMACS will automatically cause the file to recompile. “This cycle will 
continue either uatil the file compiles without error, or until you break the 
cycle by typing <etrl-U> <ctrl-X> <etrl-C>. 


The option -e to the me command allows you to invoke the error buffer by 
hand; compilation can then be performed by passing a command to the sheil 
using the <etrl-X>! command, 


‘The following list gives the MicroEMACS commands. They are grouped by 
function, 2.g., Moving the cursor. An argument giving a repeat count can 
precede # command; the default argument is 1. <ctrl-U> introduces an argu- 
ment, If it is followed by an optional minus sign ‘-' and decimal digits, the 
number gives the argument, If not, each <ctrl-U> multiplies the value of the 
argument by four. 


Moving the cursor 

<ctrl-A> Move to start of line, 

<etrl-B> (Back) Move backward by characters, 
<ese>B Move backward by words. 

<ctrl-E> (End) Move to end of line. 

<ctrl-F> (Forward) Move forward by characters. 
<esc>F (Forward) Move forward by words. 
<ese>G Go toan absolute line number in a file. 
<ctrl-N> (Next) Move to next line, 
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<etrl-P> (Previous) Move to previous line. 
<ctrl-V> Move forward by pages. 

<ese>V__ Move backward by pages. 
<ctrl-X>= Print the current position. 


<ctrl-X>G Go to an absolute line number in a file. Can be used with an argu 
ment; otherwise, will prompt for a line number. 


<esc>! Move to the line within the window given by argument; the posi- 
tion is in lines from the top if positive, in lines from the bottom if 
negative, and the center of the window if 0. 


<esc>< Move to the beginning of the current buffer, 
<esc>> Move to the end of the current buffer. 
Killing and deleting 

<ctrl-D> (Delete) Delete next character. 

<ese>D Kill the next word. 


<ctrl-H> If no argument, delete previous character. Otherwise, kill argument 
previous characters. 


<ctrl-K> (Kill) With no argument, kill from current position to end of line: if 
at the end, kill the newline, With argument 0, kill from beginning 
of line to current position. Otherwise, kill argument lines forward 
GE positive) or backward (if negative). 

<ctrl-W> Kill text from current position to mark, 

<ese>W Kill text from mark to cnrrent nos 


<etrl-X><ctrl-O> 
Kill blank lines at current position, 


in, Same as <etel=-W>, 


<etrl-Y> (Yank) Copy the kill buffer into text at the current position; set 
current position to the end of the new text, 

<esc> <ctrl-H> 
Kill the previous word. 

<ese><DEL> 
Kill the previous word. 


<DEL> —_If no argument, delete the previous character, Otherwise, kill ar- 
_gument previous characters, 
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Windows 


<ctrl-Xo1_ Display only the current window. 


<ctrl-X>2_ Split the current window; usually followed by <ctrl-X>B or <ctrl- 
X><etl-V>. 


<ctrl-X>N (Next) Move to next window, 
<ctrl-X>P (Previous) Move to previous window. 
<etrl-X>Z Enlarge the current window by argument lines. 
<etrl-X><etrl-N>- 

Move current window down by argument lines. 
-<etrl-X><etrl-P> 

Move current window up by argument lines, 
<ctrl-X><ctrl-Z> 

Shrink current window by argument lines, 
Buffers 
<ctrl-X>B (Buffer) Prompt for a buffer name, and display the buffer in the 

current window, 
<ctrl-X>K (Kill) Prompt for a buffer name and delete it. 


<ctrl-X><etrl-B> 
Display a window showing the change flag, size, buffer name, and 
file name of each buffer. 

<ctrl-X><etrl-F> 
(File name) Prompt for 2 file name for current buffer. 


<etel-X><etrI-R> 
(Read) Prompt for a file name, delete currant buffer, and reed the 
file. 

<ctrl-X><etrl-V> 
(Visit) Prompt for a file name and display the file in the current 
window. 

Saving text and exiting 

<etrl-X><etrl-C> 
Exit without saving text. 

<<ctrl-X><etrl-S> 
(Save) Save current buffer to the associated file, 

<<ctrl-X><etrl-W> ‘ 
(Write) Prompt for a file name and write the current buffer to it. 
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<ctrl-Z> Save current buffer to associated file and exit. 
Compilation error handling 

<ctrl-X>> Move to next error. 

<etrl-X>< Return to previous error. 

Search and replace 


<etrl-R> (Reverse) Incremental search backward; a pattern is searched for as 
each character is typed in. 


<ese>R (Reverse) Search towards the beginning of the file. 


<etrl-S> (Search) Incremental search forward; a pattern is searched for as 
each character is typed in. 


<escoS (Search) Search toward the end of the file. 


<eses% Search and replace. Prompt for two strings; then search for the 
first string and replace it with the second. 


<ese>/ Search for next occurrence of a string entered with the <esc>S or 
<ese>R commands; this remembers whether the previous search had 
been forwards or backwards. 


<ese>@ Toggle case sensitivity in search commands. 
Keyboard macros 


<ctrl-X>(_ Begin a macro definition. MicroEMACS collects everything typed 
until the end of the definition for subsequent repeated execution, 
<ctrl-G> breaks the definition. 


xctrl-X+) End a macro definition. 


<ctrl-X>E (Execute) Execute macro. 


Change case of text 
<esc>C (Capitalize) Capitalize the next word, 


<ctrl-X><etrl-L> 
(Lower) Convert from current position to mark into lower case. 


<ese>L (Lower) Convert the next word to lower case, 
<etrl-X><etel-U> 

(Upper) Convert from current position to mark into upper case. 
<esc>U (Upper) Convert the next word to upper case. 
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White space 
<ctrl-I> Insert a tab. 
<ctrl-J> Insert a new line and indent to current level. 


<ctrl-M> (Return) If the following line is not empty, insert a new line; if 
empty, move to next line. 


<ctrl-O> (Open) Open a blank line; that is, insert newline after the current 
position, 


<TAB> With argument, set tab indentation to argument characters. An ar- 
gument of zero restores the default of eight characters. 


Send commands to operating system 


<ctrl-C> Suspend MictoEMACS and invoke a new copy of msh, Typing exit 
returns you to MicroEMACS and allows you to resume editing, 


<ctrl-X>!_ Prompt for an msh command and execute it. 
Sewing the mark. 

<ctrl-@> Set mark at current position. 

<ese>. Set mark at current position, 

Miscellaneous 

<etrl-G> Abort a command, 

<ctrl-L> Refresh the screen, 


<ctrl-Q> (Quote) Insert the next character into text; used to insert control 
characters. 


<ese>Q (Quote) Insert the next control character into the text; same as 
<etrl-Q> 


<ctrl-T> — (Transpose) Transpose the characters before and after the current 


<ctrl-U> Specify a numeric argument, as described above, 
<ctrl-X>F Set word wrap to argument column. 


-<etrl-X><etrl-X> 

Exchange current position and mark 
Diagnostics ‘ 
MicroEMACS prints error messages on the bottom line of the screen, It prints 


informational messages (enclosed in square brackets ‘[' and ‘] to distinguish 
them from error messages) in the same place. 


‘MicroEMACS manipulates text in memory rather than in a file. No changes to 
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a file occur until the user writes edited text, MicroEMACS prints a warning 
and prompts the user whenever a command would cause ir to lose changed text. 


Because MicroEMACS keeps text in memory, it does not work for extremely 
large files, It prints an error message if a file is too large; when this happens. 
you should exit from the editor immediately, without saving the file. Otherwise, 
your file on disk will be truncated. 


See Also 
‘commands 
See the accompanying tutorial MicroEMACS Screen Editor Tutorial 


Notes 

‘This version of MicroEMACS does aot include many facilities available in the 
original EMACS display editor, which was written by Richard Stallman at 
MLT. In particular, it does not include user-defined commands. Tt also does 
not include pattern search commands. 


Note that the current version MicroEMACS, including source code, is 
proprietary to Mark Williams Company, The code may be altered or otherwise 
Changed for your personal use, but may not be used for commercial purposes, 
‘and may not be distributed without prior written consent by Mark Williams 
Company. 


‘MicroEMACS is based the public domain editor by David G. Conroy 


me.a—Archive 


‘me.a is an archive that holds the source files for the Mark Williams proprietary 
version of the MicroEMACS screen editor. If you wish to recompile 
MicroEMACS, you must first extract the source files from the archive. Use the 
cummaud ed to move to the directory where you have stored this archive, then 
give msh the following command: 


See Also 
ar, me 
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‘Check whether disk has been changed 
‘#include <osbind.h> 

#include <bios.h> 

long Mediach(drive) int drives 


Mediach checks whether a disk has been changed. drive is a number from zero 
to 15, and indicetes which drive to check: zera indicates drive A, one indicates 
Grive B, etc. Mediach returns zero if the medium has not been changed, one if 
it may have been changed, and two if it was changed. 
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Example 
This example discovers whether the floppy disks have been changed. 


inelude <osbind.n> 
maing) € 
int d, os; 
char “status(31 = ¢ Mnot™, "possibly", "definitely 9; 
for (d= 0; d<2; dee e 
de = Mediach(a); 
printfcideive Xe has ", dt!a! 
if (ds «0 |] ds > 2) 
pringf(bad status: %é\n!", de) 


alse 
printf "ss changed\n", statustdst); 


3 


See Also 
bios, TOS 


memory allocation—Definition 
The following diagram shows how Mark Williams C allocates memory. 
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BASE PAGE | Low address 
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The stack descends from the highest address in its space, toward the static data 
area; new arguments are placed on the stack in its lowest address. Everything 
from the top of the stack space to the end of the data segment is free to accept 
dynamically allocated data. 


‘The size of the stack cannot be altered while a program is running. The amount 
of stack is set by the global variable _stksize. By default, the run-time start-up 
sets _stksize to two kilobytes. Note, however, that a highly recursive function 
may cause the stack to grow larger than two kilobytes, so that it overwrites 
other data areas. This will cause your program to work incorrectly 

Should your program need more than two kilobytes of stack, include in it the 
following global statement: 


tong _stksize = nL; 
where 1 is a constant that specifies the number of bytes to allocate. 
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Example 
The following example displays the “memory map" of aGEM-DOS process, It 
demonstrates argc, argy, envp, environ, end, etext, edata, and _stksize, as well 
as how to use the header file basepage.h. 


include <basepage.b> 
dodisplay(value, name) 
long vatue; char *nane; 
t 

printf(Osz08Ux s\n", value, none); 
Hating dieplay(x) dedisplay((tong)O, 


nain¢arge, argv, envp) 
Int arse; ‘har argv, *envpl 
£ 

extern Long _stksize; 

extern char *¥environy 

extern char etext fl, edatati, endtl; 


Siaplay(oP->p ems 
displaycenvetGh); 
displaycenviront01); 
displayCarsvit)); 


if Caraven t= 0) 
displaytaravt11); 
if (argc > 2) 
displayvergytarge-12); 
displavespy: 
display(eP->p_lowtpa), 
display(aP->p_endt ined: 
display(_start) 
display(P->p_thase: 


displaycerext; 

display(aP->p tbase+BP-2p_tlend; 
display edats) 

display(aP->p dbaserBP->p dlen); 
shapley (ened; 


isplay(8P->p_obaset8P->p bien); 
displaytene); 

displayCenvirend: 

SisplayCergy); 

displaytargvesree: 
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displayt_etksize); 
displaycdarse); 
display(darav); 
displaycéervpl; 
display(aP->p hitpay; 
> 


See Also 
C language, calling conventions, data format 


menu—Definition 


320 


‘A menu is a graphics form that is used extensively in programs that run under 
TOS, It is a specialized form of AES object that uses the structure OBJECT 
described in the header file obdefs.h. For more information on this structure, 
see the entry for object. 


Each menu's object tree must be built in a special way. The root object is 2 
G_TBOX that is sized to dimensions of the screen, Note that in high resolution, 
the screen is 640 rasters wide by 400 high; in medium resolution, it 6 640 
asters wide by 200 high; and in low resolution, it is 320 rasters wide by 200 
high, The root has two children: the bar object and the screen object, 


The root object's first child is the bar object, Tt describes the menu bar, at the 
top of the screen, and is of object type G_BOX. Its length is that of the screen, 
and its width is that of a normal character plus two rasters for gutter. In high 
and medium resolutions, a character is 16 rasters high; in low resolution, it is 
eight rasters high; thus, in high resolution the bar object is 18 rasters high; in 
medium and low resolutions, it is ten rasters high. 


‘The bar object has one child: an active object, whose type is G_IBOX. The ac~ 
tlye box is sized to hold all of the titles that appear in the bar along the top of 
the screen. 


The active box, ia turn, has one or more children: the title strings, which are 
the titles of the menus. These strings are of the type G_TITLE; note that this 
type is used only with menus. By design, the first (leftmost) title must be called 
i triggers the drop-down menu that names the available GEM desk ac- 


cessories, 


The screen object is the object’s other child. It is of type G_TBOX, and it is 
sized to cover the portion of the screen that is used by the drop-down menus. 
‘Thus, it should be as wide as the screen and as high zs the longest drop-down 
menu. The screen object has one or more children: each child is a box that dis- 
plays a drop-down menu, There should be one box for each drop-down menu, 
i.e., the number of boxes and titles must be the same. Each box is of tyne 
G_"BOX; each must be wide enough and high enough to hold all of the text that 
Will be written into it; for example, if the longest string to go into it is ten 
characters wide, then the box must be at least 64 rasters wide (in high resolu- 
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tion) or the string will splash over its edge. Each box should be aligned on the 
loft with ite corresponding title; there is no need, however, to keep the various 
boxes from overlapping. Note that the Atari ST has a buffer in which to stare 
the portion of the screen that is overwritten by a drop-down menu, so that it 
can be restored when the menu is erased, This buffer can hold up to one 
quarter of the screen, or 64,000 pixels; no box should exceed this limit, or 
debris will be left on the screen when the menu is erased, 


Each box can have one or more children, called names. Each name is of type 
G_STRING, and names the particular option that you are offering the user. 
Note that all the mames must be as wide as the box; otherwise, the box will 
“Jeak", and cause more than one selection to be illuminated when the mouse 
pointer is moved into that box. The Y coordinate for each mame must be in- 
creased by one line's height; for example, if a box has three names, the ¥ coor- 
dinate of the first should be zero, that of the second should be 16 (in high 
resolution, eight in medium or low resolution), and that of the third should be 
32. This will keep the names from overlapping, which could possibly have dis 
astrous results. As always, the X and Y coordinates of an object are relative to 
those of its parent, 


The first (leftmost) box is special in that the AES can manipulate its name ob- 
jects. By design, the first box must have eight name children. The first name 
can be defined by the user. The second name consists of a row of hyphens, its 
state is set to DISABLED, which causes it to be written in gray, rather than 
solid, letters, The next six names should point to empty strings. These will be 
filled in by the AES with the names of the available desk accessories. The AES 
will alter the size of the leftmost box if fewer than six are available, 


The following “geneological table” shows the object tree for a menu that has 
two drop-down menus, the latter with three entries. The numbers indicate each 
element's place in the object tree, and are used to set the parent-child~sibling 
pointers, These are set by the order in which the elements are loaded into the 
object's array: 
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The menu should be invoked with the menu_bar call; the AES will handle the 
rest, Note that, as shown in the above example, menu_bar regards as sig- 
jcant the order in which the elements of a menu are loaded into the object 

array. The order should be as follows 

root 

bar 

active 

title(s) 

screen 

first menu box 

first items 


last menu box 
last Items 


When the mouse is used to select a menu entry, the AES generates a message 
that contains that object’s index number within the menu tree; use evnt_mesag 
to receive the message and initiate the proper response. The AES will 
automatically handle all invocation of desk elements; you do not need to write 
rode for them. 

Example 

This example clears the screen and displays @ menu that lists all of the GEM 
desk accessories, Note that the objects are sized in rasters for a high-resolution 
screen, 


include <aosbind. b> 
‘Finclude <ebdefe.h> 
include <gendefe.h> 
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vs 

+ ess cre 16) | order t raster thick 

x (BLACK <e 12) | CFL eotors BLACK 

* (BACK << 8) | CText color] 

* (eee 7) | Murn on replace biel 

* ee h) | EFTUL pattern to grey! 

* Together make one nysbtel 3 

* Lack order colort 

tt 

‘define COLOR Ox0TDFOL 

ns 

* 0 << 16) {order thickness 02 

: (BLACK << 12) IFiLL colors BLACK = 11 

* (SITE << 8) EText color 

* cen Replace bit ont 

* eh) [FIL pattern to solid tone nybotel? 

* waite (order color; WHITE = 0} 

” 

(* steings used in the menu object */ 

char deske) = 

char quita = 

char inet] = 2ssee- ton " 

char blankt) = #4; 

J Define an object that masks the screen */ 

BsgCT maskt) = € 

TANI 7 T/ type / Flags / state /specificetions X/ Ys wy HAY 
+, “1, 1, 680K, LASTOB, NORMAL, SPEC, 0, 639, 399 

i 

J vetine the menu object */ 

DgUECT menutl = € 

TN Wf T) type / flags / state /specit./ X/ YW) HAY 
“1, 4, GHROK, NONE, NORMAL, CxOL, 0,0, 639, 399, /* ROOT 4/ 
4, 2) 2 Gaon, NONE, NORMAL, COLOR, 0, 0, 639, 18, /* BAR 2/ 
1, 5, 5) @TR0x, WOME, WORMAL; OxOL, 0,0, 84, 18, /* ACTIVE 47 
2-1) -1, CFITLE, Nowe, —NomWL, deck, 0; gi, 4B, y= time + 
0, 5, 5 G1BOK, NONE, NORMAL, OxdL, 18, $39, 140, /= SCREEN */ 
4, 6, 13, GBOK, NONE, NORMAL, coLoR, 
7,3, -1 G.STRING, NORE, ORNL, quit, 
By +1) +1) GISTRING, NOME, DISABLED, Line, 
9) 1-11 GSTRING, NONE, NORMAL, blank, 
10) <1! <1! @IsTRING, Nowe, NORMIL, blank, 
31, 71-1) GSTRING, NOE, NORMAL, Blank, 
32-1 4) csTRING, HOWE, NORMHL, Blank, 
43, -1) +1; GoSTRING, NONE, NORMAL, blank, 
3) -1) -1) GLSTRING, LASTOB, NORMAL, Blank, 

% 
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rain ¢ 
int butfert8) 
int nowhere /* Unused pointers point here */ 
appl initor /# Begin application * 
graf _ouse(ARROY, Snowhere);  _/* Mouse ptr. to array */ 


obje_draw(nask, ROOT, MAX DEPTH, 0, 18, 639, 380); 
72 Mask the screen */ 
rena borcmeru, 1) 7 Shou menu bar */ 


forczs) € 
‘evnt_neseg(butfer); 


if (Gutfer 0] == Mi SELECTED) € 
si toh(buffert41) © 
case 6: J ise, object 6 clicked */ 
rent barcmerd, 0D; 
applexitO; 
exit); 
cefault: 
break: 
d 
> 
BY 
, 
See Also 


AES, object, TOS, window 
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Show or erase the menu bar 

include <aesbind.h> 

#include <obdefs-h> 

Int menu_bar(tree, eraseshow) OBJECT *iree; int eraseshow; 


menu_bar is an AES routine that shows or erases the menu bar; the menu bar is 
the bar that appears at the top of the screen and names the menus that are 
available to the user. tree is the name of the object tree being used. eraseshow 
indicates whether you want to show or erase the menu bar: zero indicates erase, 
and one indicates show. menu_bar returns zero if an etror occurred, and a 
number greater than zero if one did not. 

Example 

For an example of how to use this routine, see the entry for menu, 

See Also 

AES, menu, object, TOS 
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meau_icheck—AES function (libaes.a/menu_icheck) 
Write or erase a check mark next to a menu item 
#include <aesbind.h> 
#include <obdefs.h> 
int menu_icheck(éree. item, eraseshow) OBJECT "tree; int item, eraseshow, 


menu_icheck is an AES routine that draws or erases a check mark next to a 
selected menu entry. tree points to the object tree that holds the menu, and ad- 
ject is the object within the tree that is being handled. eraseshow indicates 
whether you want to show the check mark or erase it: zero indicates erase, and 
one indicates show. menu_{eheck returns zero if an error occurred, and a 
number greater than zero if one did not. 


See Also 
AES, menu, object, TOS 


menu_fenable—AES function (libaes.a/menu_ienable) 
Enable or disable a menu item 
#include <aesbind.h> 
#include <obdefs.h> 
int menu_ienable(tree, object, disable) 
OBJECT *tree; int object, disable: 


menu_ienable is an AES routine that enables or disables a menu item. A dis- 
abled item is displayed in faint letters and cannot be clicked by the user. tree 
points to the object tree that contains the menu, and object is the number of the 
object within the tree. disable indicates whether the item should be enabled or 
disabled: zero indicates disable, and one indicates enable. menu_ienable 
returns zero if an error occurred, and a number greater than zero if one did not. 


See Also 
AES, menu, object, TOS 


menu_register—AES function (Iibaes.a/menu_register) 
‘Add a name to the desk accessory menu list 
include <aesbind.h> 
#include <obdefs.h> 
int menu_register(accessory, teststring) int accessory; char *teststring; 


menu_register is an AES routine that adds a name to the desk accessory menu 

. accessory is the ID of the desk accessory. teststring points to the desk ac~ 
cessory’s desk menu test string. The test string is a template used to check 
whether text typed by the user, if any, is of the correct type (e.g., lower-case 
letters only). For more information about the template, see the entry for menu. 


menu_registerreturns the desk accessory’s identifier, from zero through five 
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See Also 

AES, desk accessory, menu, object, TOS 

Notes 

Because only six desk accessories can be used at any one time, only six items 
can be displayed on the desk accessory menu, 


menu_{ext—AES function (libaes.a/menu_text) 


Replace text of a manu item 

#include <aesbind.h> 

#include <obdefs.h> 

int menu_text(¢ree, object, text) OBJECT “tree; char *text: int object: 


menu_text is an AES routine that changes the text for a menu item. free points 
to the object tree for the menu, and object is the number of the object within 
the tree that holds that particular menu entry. fext points to the text string to 
be plugged into the menu, menu_text returns zero if an error occurred, and a 
number greater than zero if one did net. 


See Also 
AES, menu, object, TOS 


menu_tnormal—AES function (libaes.a/menu_tnormal) 


isplay menu title in normal or reverse video 

include <aesbind.h> 

include <obdefs.b> 

int menu_tnormal((ree, object, video) OBJECT *iree; int object, videos 


menu_tnormal is an AES routine that displays the menu title in normel or 
reversé video. free points to the object tree that encodes the menu, and onject 
is the number of menu title within the tree. video indicates whether you want 
the title to be in normal or reverse video zeto indicates reverse video, and one 
indicates normal. menu_tnormal returns zero if an error occurred, and a mum= 
ber greater than zero if one did not. 


See Also 
AES, menu, object, TOS 


metafile—Definition 


‘A metafile is a file of VDI instructions that can be stored on disk and incor- 
porated into other programs. This allows you to create “boiler-piate” images 
‘that are transferred easily. 

Note that a metafile consists of @ set of VDI instructions, rather than device 
dependent bits. This allows you to edit such a file easily to alter its aspects. 
More importantly, because the elements of an image are described logically 
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rather than absolutely, it allows the elements to be manipulated easily, and the 
image as a whole to be mancuvered. This allows you to create images inde- 
pendent of the the type or resolution of the device on which they are displayed, 


Consider, for example, the example of the bouncing colored ball used in the 
Atari demonstration program. At present, that program has a set of “snapshots” 
of the ball in different positions; to animate the ball, the program simply cycles 
through the snapshots. If this program were stored in a VDI metafile, however, 
a programmer could describe how each plane on the surface of the ball is logi- 
cally connected to its neighbors; by setting parameters, then, the entire ball in 
all of its aspects could be resized easily or moved about the screen, This, in 
turn, would allow the programmer to create a user interface, in which the user 
could “zoom in” toward the ball, zoom out, move the ball around the screen, 
change its rate or direction of rotation, ete. 

Metafile structure 

For a full description of the VDI metafile structure, see Appendix C to volume 
1 of the GEM Programmer's Guide, The following briefly summarizes the 
‘metafile format, 


Each metafile begins with a 16-integer header, structured as follows: 


1 Always set to OxFFFF, 

2 VDI version number: 100 times the major version number, plus the 
minor version number. 

3 Type of coordinates; zero indicates normalized device coordinates 
(NDO); two indicates raster coordinates (RC), One is reserved by TOS. 

4-7 Respectively, minimum width and height, and maximum width and 


height required to display image in the file. These are set with the 
function v_extent_mots; otherwise, they are set to zero. 


8-16 Reserved; always set to zeroes. 


‘The header is follow by a series of VDI entries; each consists of an srray of ints, 
in the following order: 


0 The VDI function's opcode. See the list below for the appropriate ap- 
code for each legal VDI routine. 
1 The number of vertices (ie., endpoints or corners) in the figure being 


drawa, 
‘The number of integer parameters passed to the VDI routine. 


The VDI routine’s sub-opcode; see the table below for each routine’s 
appropriate sub-opcode. 

4-n The settings for each vertex. The number of vertices described cor- 
responds to the value in 1. 
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rad-m The values for each integer parameter. The number of parameters 
described corresponds to the value in 2. 


Finally, each metafile closes with an integer set to OxFFFF_ 


Customized routines can be inserted into 2 metafile with the function 


y_meta_write. 


Metafile routines 


‘The following VDI library routines can be incorporated into metafiles. The 
first column gives the routine’s opcode, the second gives its sub-opeode, the 
third gives its name, and the fourth a brief description of its action. 


x Oo 
4 0 
5 2 
s 2 
5 20 
5 21 
5 2 
3 23 
6 
1 
8 
9 
u 
ul 
ul 


oo 


eccocooco ooo CowmIAUEUnHOS 


y_etrwk 
youpdwk 
yTexit_cur 
yTenter_cur 
y_form_ady 
yCoutput_window 
Yrelear_disp_list 
+_bit_ifiage 
yopline 
yopmarker 
yogtext 
yfillarea 
yobar 
Y_piestice 
yeirele 
y_ellipse 
y_ellare 
yoellpie 
y_rbox 
yorfbox 
vat_height 
yst_rotation 
¥s_color 
ysI_type 
ysl_width 
yst_color 
ysmi_type 
ysm_height 
ysm_eolor 
yst_Tont 
yst_color 
vsfLinterlor 
vsf_style 
ysf_eolor 


clear a virtual device 

update workstation (Flush buffers) 
exit from alphabetic mode 

enter alphabetic mode 

advance page on hard-copy device 
print portion of a virtual device 
clear a printer’s display list 

print a bit-image file 

draw a polyline 

draw a polymarker 

output graphics text 

flood enclosed area with fill pattern 
draw an outlined, filled rectangle 
draw a circular arc 

draw a circular pie segment 
drawa circle 

draw an ellipse 

draw an elliptical arc 

Graw an elliptical pic segment 
draw rounded rectangle 

draw rounded rectangular fill area 
set graphics text height, in pixels 
set angle of graphics text 

set mix for a color 

set polyline’s pattern 

set polyline width 

set polyline color 

query graphics text attributes 
query character cell's height 
query color settings 

set graphics text font 

set graphics text color 

set fill type 

set fill style 

set fill color 
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32-0 swr_mode set writing mode 
39 0s tst_aligmment _set graphics text alignment 
104 0 —_ysf_perimeter set drawing of perimeter 
106 0 —yst_effeets set graphics text special effects 
107 0 sst_point set graphics text height, in points 
108 0 sl_ends set polyline end types 
120 ysf_udpat set user-defined fill pattern 
113 0 whundsty set user-defined polyline style 
114 0 w_teefl draw a rectangular fill area. 
129° 0 woelip clip an area of the virtual device 
See Also 


TOS, y_extent_meta, y_write_meta, VDI, vm_filename 


Notes 
Metafiles need the VDI's GDOS in their operation, They should not be used if 
the GDOS is not present in your edition of VDL. 


mf—Command 
‘Measure space left in RAM 
mf 


mf is a command that measures the amount of free space left in RAM for 
program execution, It takes no arguments, 


See Also 
commands, df, msh 


Mfpint—xbios function 13 (osbind.h) 
Initialize the MFP interrupt 
#include <osbind.h> 
winclude <xbios.h> 
void Mfpint(interrupt, vector) int interny 
Mfpint initializes the multi-function peripheral (MFP) interrupt, and returns 
nothing. This routine allows a programmer to trap a hardware interrupt in her 
program. interrupt is the number of the interrupt to be set, 0 through 15, as 
follows, going from lowest to highest priority: 


; char "vector; 
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MEP_BITO 9 — 1/0 port bit o 
MFP_BITI 1 undefined 
MFP_BIT2 2 undefined 
MEP_BIT3 3 undefined 
MFP_TIMD. 4 timer D, RS-232 baud rate generator 
MEP_TIMC 5 timer C, system 200-hz. clock 
MFP_BITS 6 YO port bit 4 
‘MEP_BITS 7 undefined 
MFP_TIMB 8 timer B 
MFP_XERR 9 —_RS-232 transmit error 
MEP_EMPT 10 RS-232 transmit buffer empty 
MFP_RERR 11 RS-232 receive error 
MFP_FULL 12 RS-232 receive buffer full 
MFP_TIMA 13. timer A, user programmable 
MFP_BIT6 14 1/0 port bit 6 
MFP_BIT7 15 1/0 port bit 7 

vector points to the interrupt routine to be set. 

See Also 


Adisint, Jenabit, TOS, xbios 


Mfree—gemdos function 73 (osbind.h) 
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Free allocated memory 

include <osbind.h> 

long Mfree(memor}’) long memory: 

Mfree frees memory allocated by the function Malloc. memory points to the ad~ 


dress of the memory to free. Mfree returns 0 if memory could be freed, and 
non-zero if it could not, 


Example 
The following example prints the number of bytes currently free and the num- 
ber allocated. 
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Winetude <osbind.h> 


maint) ¢ 
unsigned Long menteft; 
unsigned long menhere; 
char "alent: 
- 
+ This First 'printf! is needed to make the nunbers 
* Look right, because printf malloc's menory for the 
FILE buffer 
” 
printf(*Test of Malloc(), MfreeC) and Msheinky\nt); 


printfcwmatx bytes free, %BLx bytes allocated\n, 
(renlaft = Malloce-11)), OL): 


nenhere = nenletts>1; 

sinen = (cher *) Malloe(menbere); 

printf(Blx bytes free, ¥BLx bytes allocated (xBLOW", 
Metlace-1L), mealeFe hat toctIL), menhered; 


Mshrink¢almen,0x1000L); 
fCRBLx bytes free, XBIx bytes allocated (3BLx)\n", 
Matlecc-11), menleft-Mallec(-1L), Ox1000.); 
Mfreetatnen); 
printf(Iaalx bytes free, Z8lx bytes allocated (28Lx)\n", 
Malloct-IL), memleft-Matecc-1L3, 01); 


5 


See Also 
gemdos, Malloe, Mshrink, TOS. 


Notes 

Do not attempt to Mfree blocks of memory not directly allocated by Malloc. 
Memory freed by Mfree is not inserted into the areaa used by malloc, but is 
returned to the system. 


Midiws—xbios function 12 (osbind.b) 
Write a string to the MIDI port 
#include <osbind.h> 
Hinclude <xbios-h> 
void Midiws(counr, pointer) int count; char *pointer; 


Midiws writes a string to the musical instrument device interface (MIDI) port, 
and returns nothing, count gives the number of characters that will be sent, 
minus one; and iuffer points to where the characters are stored. Note that this 
routine will transmit coww characters; NUL characters will be used Uke any 
other character. 
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Example 
‘This example plays some notes on 2 MIDI instrument 
through the MIDI-OUT plug. 


include <osbind.h> 
/* MIDI status byte values */ 


dete NOTE_OFF (0x60) 1 Key off comand */ 
det ine NOTE_ON (0:90) * Key on command */ 


{7 Sone useful things to know... */ 
define MIDDLE_C (60) 


HeeFine ¢_OFFSET (0 
‘efine D_OFFSET (2) 
Heefine EOFFSET (4) 
Aefine FLOFFSET (5) 
define G_OFFSET (7) 
define ALOFFSET (9) 
Adofine 5 OFFSET (11) 
define FLAT 1) 
‘tdefine SHARP (1) 
‘define OCTAVE STEP (12) 


unsigned char notes 128); (7 Note counters... */ 
ley dovntnote offset) 
int nate_offset; ¢ 


int midi_note: 
char midi_but (61 


connected to the ST 


if (Cmidi_note-MIDDLE_cenate_offset) < 0 || midi_note >127) 
return J Rawurn $f out af renge */ 


notestnidi_notele; 7 Mark as key-dosn.. 
sidt_buf t0i=s 

nnigt_buf 11=nfdi note; 
ili_but (230340; 
Kusc2, 
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key uptrote offset) 
int note offset; ( [Note */ 


ine midi_noves 
char migi_buFti; 


if midi_note-MIODLE_Cinote offset) < 0 || midi_noxe > 127) 
7 Return ff out of range */ 


If (notestnidi_noted-- < 09 


7 Decrement down count 
Pe Note off... 47 


> 
cleanup) € 
char mig_buF (258); {[* buffer for comands */ 
char "mp; i Ard a pointer. */ 
int i=0; 7* A counter, */ 
int 20) J Another counter */ 
mp = midi _but 
snpre = NOTE_OFF; 
wile (F< 128) € 
whilecnotestid. t= 0) ¢ 
notes {i3-~ 
sipet = 
sopet = 0X60; 
ce 
y 
itte > 9) 
Widiwacecet, midi_bufs 
> 
/* batay for a Little while -- Use the vertical syne for timing.*/ 
delayin) 
int ni ¢ 
int 17 


iniletnes 50) € 
Forcis35 ; 90; f 
Yeynet 
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ey. dosnt OFFSET; 
delay(2) 

oy down(E OFFSET; 
delay(2i 

oy down(G OFFSET); 

delay(2); 

ey down(C_OFFSET+OCTAVE_STEP); 
delayes); 

key wpe OFFSEN); 
key" un(G_OFFSEN); 
ey_downtF_OF FSET 
‘key_Gown¢A_ OFFSET); 
delay(20): 

clean up; 


> 


See Also 
TOS, xbios 


mkdir—Command 


Create a directory 
mkdir directory 


mkdir creates directory, Files or directories with the same name as directory 
must not already exist, directory will be empty except for the entries +, the 
directory’s link to itself, and *..’, its link to its parent directory. 

See Also 

commands, msh, rm, rmdir 


mktemp—General function (libe.a/mktemp) 
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Generate a temporary file name 
char *mktemp(pattern) char * patterns 


mktemp generates @ unique file name, for such purposes as naming intermediate 
data files. 


‘Note that the functions tmpnam and tempnam assemble temporary file neme 
and then call mktemp. These routines ease somewhat the difficulty in creating a 
proper name for a temporary file, 
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See Also 
msh, tempnam, tmpnam 


modf—General function (libe.a/modf) 
Separate integral part and fraction 
double modf(real, ip) double real. ip: 


modf is the floating point modulus function. Tt returns the fractional part of its 
real argument, which is a value f in the range 0 <= /< 1. Italso stores the in 
tegral part in the double Incation referenced by ip. These numbers satisfy the 
equation real =f + *ip. 

See Also 

atof, ceil, fabs, floor, frexp, Wdexp 


modulus—Definition 
Modulus is the operation whereby the remainder is derived from a division 
operation; for example, 12 moduld 4 equals 0, because when 12 is divided by 4 
it leaves no remainder. The term “modulo” also refers to the product of a 
modulo operation; in the above example, the modulo is 0. In C. the modulo 
operation is indicated with a percent sign “%4'; therefore, 12 modulo 4 is written 
12%4. 


msh—Command i 
msh is the Mark Williams micro-shell, which is designed for use under TOS. Tt 
combines aspects of the Bourne shell and the Berkeley C shell into one com- 
mand that is powerful and easy to use, 


msh is a command processor. It finds commands and executes them either singly 
or in batches; and it allows the user to direct the output of a command to a 
deyice, into a new file, or to another command for further processing. Tt can 
replace text with symbols defined by the user, or with wildcards that are ex- 
panded according to carefully defined rules, 


The simplest command consists of a list of words; the words are separated from 
each other by spaces or tab characters, and the list is terminated by a <newline> 
sequence. Each word may contain history substitutions, variable substitutions, 
file name substitutions, quoted characters, quoted strings, or file redirection. msh 
also supports aliasing, for use in batch files and seripts. These are discussed 
below. 


Several commands may be placed on the same line; the commands are then 
separated with semicolons or other command separators; these are outlined 
below. A list of commands may be grouped into a single command by enclosing 
the list within parentheses, 
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Both simple commands and lists of commands be made to extend over more 
than one line by typing a slash */’ before pressing the <return> key. 

History substitutions 

4 history substitution allows you to use all or part of a previously entered com- 
mand or a shell variable in your present command, For example, typing 


‘echo foo 
echo >ber 


is equivalent to typing: 
echo Foo 
‘echo foo >Bar 
The history substitution Moo tells msh to repeat all of the previous command 
echo foo; if msh does not find foo in history, it looks for the shell variable foo. 


‘Typing t repeats the nth command before the present one, Note that you must 
tell msh how many commands to save; for example 


et histarya8 


saves the last eight commands issued, The default setting is one. To see what 
commands have been stored in the history buffer, typ 


set in history 


History substitutions may be used anywhere on the command line, For ex- 
ample, typing 


Ls \documents\seripts\editors 
feene 00 7 1-7 


is equivalent to typing 
Ls \documents\seripts\editers 
fecho foo ; Le \docunents\seripts\editors 
Note, too, that history substitutions can use variable names, 


Variable substitution 
A variable is a symbol defined by the user 
the command 


the set command; for example, 


set ¥eecho foo! 


declares that X is a symbol equivalent to the string echo foo. When a variable is 
used in a msh command line, it must be preceded by a dollar sign ‘$' or an ex- 
clamation point“, For example, to call the variable set in the above example, 
type SX or !X. When it sees a token that begins with either of these punctuation 
marks, msh searches for it first on the list of variables that have been assigned 
with the set command, then on the list of those assigned with the seteny com— 
mand, and finally on the list of tokens that it received from TOS or from the 
parent shell, For example, if you type 
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Set clsstecho S¢esc)eM 


(where <ese> indicates the escape character) and then type 
Sets 

msh will expand this variable into 
echo “te 


and then execute the echo command with the argument <ese-E, which in turn 
clears the screen, 

The difference between $name and ‘name is that the latter may include com- 
mand separators because it is rescanned as input, whereas the former is not res- 
canned. For example, the variable set with the command 


echo f20 ; acho bart 
should be reference with the token !X rather than SX. Command separators are 
described in detail below. 


File name substitutions 
File name substitutions contain the punctuation marks []?* {}. The following 
notes what each punctuation mark does: 


(ist), [2-2] 
‘Match any of the characters /, i, s, or ¢, or any character in the range a-z. 
2 Match any one character or no character. 
+ Match any character, any string of characters, or no character. 
list) Braces enclose a list of words that are each combined with the remainder 
of the word. 


Character quotations 

A quotation is used when you want msh to disregard the special meaning of a 
character and read it merely as a literal character. In general, prececing & 
character with a slash will remove the special meaning of a character, except 
under the following circumstances: 


1, A slash followed by an end-of-file indicator is always an error. 


2. A slash followed by a <newline> becomes a spact 
the next line, 


and continues input on 


3. When set between ""s or ’s, a slash followed by a <newline> translates 
into <newline>, and /" becomes a literal quotation mark. All other 
characters quoted with */’ are left untouched. 
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4, Within literal quotations, */” is literal. 


Quoted strings 

Strings may be quoted by enclosing them in apostrophes or quotation marks. 
Quoting a string means that msh or a command is to accept it literally, Note 
that quoting a string with apostrophes prevents any further expansion: all 
wildcards and variables will be treated as literal characters. Quoting a string 
with quotation marks, however, tells msh to treat white space as part of the 
string, but allows further expansion of variables. The following exercise will 
demonstrate how these forms of quotation differ: 


set Asma" 


2 
se 
se! 


File redirection 
‘The term file redirection means redirecting the input or output of a command 
into a file. The following redirection operators are recognized by meh’ 


> file Redirect output of a file into file, If file already exists, replace its con 
tents with the output of the command. 

>& file 
Redirect the output of a command and any diagnostic messages it 
produces into file. 

>> file 
‘Append the output of a command onto /ilé. If file does not exist, eroate 
it and fill it with the output of the command, 

>>& file 
‘Append the output of a command and all of the diagnostic messages it 
generates onto file. If file does not exist, create it and fill it with the out- 
put and diagnostic messages generated by the command. 


< file Use the contents of file to control the execution of a command. 


Separating and joining commands 
Commands can be separated or joined on the same command line by using the 
following marks: i 


3; Execute commands sequentially. 


&& Execute commands sequentially until one terminates with non-zero exit 
status (.e,, until an error occurs in one), 


| Form a pipe between the commands; feed the standard output of the 


command oa the left of the ‘| into the standard input of the command on 
the right. 
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|& Form a pipe that passes both the output of the command on the left and 
any diagnostic messages it produces as input to the command on the right 


|| Commands separated by ‘||’ are run sequentially until one terminates with 
zero exit status (i.e., executed without error). 


Commands 
Mark Williams C includes a number of commands that are designed to bé used 
with msh. For a list of these commands and a brief description of each, see the 
entry for commands. If you need help with msh or any of its built-in com— 
mands, type help and the name of the command for which you need help. msh 
will print on the sereen a summary of how to use that command, 

Setting the environment 

msh allows you to set a number of environmental variables. msh uses some of 
these variables, and makes all of them available to programs that run under it 
A program can read these variables by using the function geteny. Environaien- 
tal variables can be set or changed with the command setenv, and erased with 
the command unseteny, Typing seteny without an argument will display the list 
of environmental variables plus their settings. 

For Mark Williams C to work properly, the following environmental parameters 
must be set; 


HOME — The default directory: where msh performs a task when no other 
directory is named. 


INCDIR Name the directory in which ce searches for header files and other 
text files to be included in compilation, 

LIBPATH Name the path along which ce searches for the executable files For 
the compiler and the linker i., ec0.prg, cel.prg, cc2.prg, c¢3.prg 
erts0.0, ld.prg, and the libraries. 

PATH This environmental variable consists of a list of directory prefixes 
that are separated by commas. These prefixes name the directories 
that are searched in order for commands or batch files to be run 
For example, typing 

PATH = Abin, \tib 
will ensure that msh will search the the current directory, then the 
directories \bin and \lib, in that order, to find the executable file 
named in a command, 


SUFF This consists of a list of file-name suffixes that are separated by 
commas. These suffixes are appended to the given command name 
when searching the directories named in $(PATH), 


TMPDIR Name the directory 
See the Lexicon entry environment for more information. 


nto which temporary files are written. 
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Shell variables : 
‘The following variables control the operation of msh, Some can be set with the 
sei command, Typing set without an argument will dispiay a list of all current 
variables, both those set by the user and those set by msh: 


history Set the length of the history list, For example, to set the history 
variable to eight, type the following: 


set history=8 


This allows you to invoke any of the last 
the form !-n, 


ight commands by using 


wd ‘The current working directory, This variable cannot be reset by 
the user. 


prompt This variable holds the prompt string. The defaul 


status This variable holds the exit status returned by the last command 
executed. It should not be reset by the user, 

Command files 

msh reserves the variables $0 through $9 for arguments passed on a command 

Tine, This allows you to write shell scripts whose variables can be set when you 

run the script, 


For example, the following commands could be typed into the file foo: 

ce -V -FS1 82.83 Am 
Thereafter, typing foo followed by the names of up to three C source files will 
compile the files with the floating point printf routines, and link in the mathe- 
matics library. 
The profile file 
Whenever you invoke msh from the GEM desktop, it automatically reads a file 
called profile and executes all of the commands that it finds therein. By al- 
tering your profile, you can customize msh to suit your preferences and tasks at 
hand, 
See Also 
commands, environment, set, setenv, wildcard, unset, uaseteny 


Mshrink—gemdos function 74 (osbind-h) 


Shrink amount of allocated memory. 

#include <osbind.h> 

Jong Mshrink(begin, length) int n; long begin, length; 

Mshrink shrinks the amount of memory allocated by a program, and returns 
dynamic memory to the free memory pool. begin points to the beginning of the 
space to be returned, and fengrh indicates the amount of memory to be 
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returned. Mshrink returns zero if memory could be de-allocated, and non-zero 
if itcould not, 

Example 

For an example of how to use this function, see the entry for Mfree. 

See Also 

gemdos, Malloc, Miree, TOS 

NOTES 

‘The gemdos call has a third parameter that is always zero; the Mshrink macro 
inserts this parameter automatically 


msleep—Command 
Stop executing for e specified time 
msleep milliseconds 


msleep suspends processing for a set time. milliseconds is the amount of time to 
suspend processing, in milliseconds. 


See Also 
commands, sleep, TOS 


mtoh—Command 
Redraw the screen from medium to high resolution 
mtoh 


moh redraws the screen, moving from medium to high resolution. 


See Also 
commands, htom, Itom, mtol, TOS 


mtol~Command 
Redraw the screen from medium to low resolution 

mtol 

mtol is a command that redraws the screen, moving from medium ta low 
resolution, 

See Also 

commands, htom, Item, mtoh, TOS 


mtype,h—Header file 

The header file mtype.h assigns a code number to each of the processors sup- 
ported by Mark Williams C compilers. These include the Intel 8086. 8088, 
80186, and 80286; the Zilog 28001 and Z8001; the DEC PDP-11 and VAX; the 
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IBM 370, and the Motorola 68000. 


See Also 
header file 


my—Command 
rename files or directories 
my oldfile newfile 
my file... directory 
my renames files. In the first form above, it changes the name of oldfile to 
newfile. If newfile previously existed, my deletes its former contents; if not, my 
creates it. If newfile is a directory, my places old{ile under that directory. 


In the second form, my moves each file argument into the directory argument. 
If the source and destination files are on different disk drives, my copies the 
source to the destination and removes the source. 


my will not copy directories between devices and will not remove directories 
that occupy the destination of the command. 


See Also 
commands, ep, msh 
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nested comments—Definition 
The C Programming Language declares that comments cannot be nested, The 
-YCNEST option to Mark Williams C allows nested comments, and prints 2 
warning whenever they occur. 


The following gives.an example of properly nested comment 
J nested /* comment */ */ 


Note that the open-comment and close-comment s 
Following shows improperly “nested” comments, 


mbols are balanced. The 


fF pat 
7 nested 
7 coment */ 
See Also 
ce 


Notes 
‘A program with inappropriately nested comments will fail if the option is used, 
but will compile correctly if it is not used. A program with correctly nested 
comments, however, will compile correctly if is used, but will fail if it is not 
used. Tn general, it is best to use if you use nested comments in your program, 
to ensure correct compilation of your program, 


newline—Definition 
Mark Williams C recognizes the literal character *\n' for the ASCIL newline 
character LF (\012). This normally feeds the line and returns the carriage. 
This character may be used as a character constant or in a string constant, like 
the other character constants: \a', which rings the audible bell on the terminal; 
‘\b', to backspace; *\f", to pass a formfeed command to the printer; *\r', for a 
carriage return; "\t, for a tab character; and "\v’, for a vertical tab character. 


See Also 
ASCII, character constants 


Notes 
On the Atari ST, *\n' must be used with the carriage return character ‘\r° if the 
program does not go through STDIO. 


am—Command 
Print a program’s symbol table 
am [ -adgnopru } file 
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nim prints the symbol table of each file in its argument list, Each file argument 
may be an Mark Williams C object module or an object library built with the 
archiver ar. If an argument is a library, nm prints the symbol table for each 
member of the library. 

The first argument selects one of several options. It is optional; if present, it 
must begin with '-'. The options are as follows: 

~a Print all symbols. Normally, am prints names in a C-style format and ig- 

ores symbols with names inaccessible from C programs. 


-d Print only defined symbol. 
-g Print only global symbols. 


=n Sort numerically rather than alphabetically. nm uses unsigned compares 
when sorting symbols with this eption, 

0 Prepend the file name to each output line, 
=p Print symbols in symbol table order, 
=r Sort in reverse order. 
- Print only undefined symbols, 
By default, nm sorts symbol names alphabetically. Each symbol is followed by 
its value and its segment. For relocatable object modules, the letter 'U" appears 
in place of a value if the symbol is undefined, If the file is an executable 
program, the value is the address of the symbol, The segment type designations 
for global symbols are shown below. 

SI shared instructions 

PI private instructions 

BI _ instruction space BSS 

SD shared data 

PD private data 

BD data space BSS 

D debug table 

A absolute 

© common 


Static symbols have the same segment type descriptors in lower-case letters. 


See Also 
ce, commands, Id 


notmem—General function (libe.a/notmem) 
Check if memory is allocated 
int notmem(pér) char *ptr 
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notmem checks if a memory block has been allocated by malloc, Imalloc, 
realloc, calloc, or lealloc. The pointer pir indicates the block to be checked. 
notmem searches the arena for pir; it returns one if pir has not been allocated, 
and one if it has. 

See Also 

arena, calloc, free, malloc, realloc, setbuf 


n,out—Definition 


n,out is the format used by the Mark Williams C compiler, assembler and linker 
to generate their output, 


n.out first gives global information and information about the size of exch seg- 
ment. Segments of the indicated size follow the header in a fixed order. n.out 
defines the header structure for the 68000 as follows: 


struct Idheader ¢ 
short (magic; 
short (flags 
short (eachine; 


” 

All elements of the mout header are stored in canonical byte order. 1_magic is 
the “magic number” that identifies a load module; it always contains 0407. 
1, fag coveni ig inh alosie Sis yn ke josemedile: | sablon ie 
the processor identifier, 1_tbase is the start of the text segment. ILentry con- 
tains the machine addstes where cresvion ot the modste sommes i_ssize 
gives the size of each segment, 


size prints the segment sizes of the n.out format header, nm lists the symbols, 
and strip will remove the symbols. 


See Also 
as, Id, nm, size, strip 


NUL~Definition 


NUL is the character ASCII 0 and, in C, signals the end of a string. It is 
represented as ‘\0'. Note that NUL is defined as part of the string it is ter- 
minating; therefore, a string that is defined to be 30 characters long in fact 
holds 49 printable characters plus NUL. 
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See Also 
ASCH, string, NULL 


NULL—Definition 


NULL is defined in the header file stdio.h. It is the null pointer (char *)0, 
which is a pointer filled with zeros. Numerous routines return this value to in- 
dicate failure; it is useful as a return value because it points nowhere, and so 
removes the possibility of accidentally destroying a section of memory after 
failure, 

See Also 

manifest constant, NUL, pointer, stdio.h 


Notes 
References through NULL on the Atari ST cause a bus error, i.e., two cherry 
bombs appear on the screen. 


nybble—Definition 


346 


‘A nybble is four bits, or half of an eight-bit byte. The term is generally used to 
refer to the low four bits or the high four bits of a byte; thus, a byte may be 
said to have a “low nybble” and a “high nybble”. One nybble encodes one 
hexadecimal dij 


See Also 
bit, byte 
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obdefs.h—Header file 
TOS header file 
‘#include <obdefs.h> 
obdefs-h is a header file that contains TOS common object definitions and 
structures. It defines numerous elements used in programs written for the Atari 
ST, such as definitions of color settings, editable fields, and fonts. 
See Also 
header file, object, TOS 


Winclude <aesbind.h> 
winclude <obdefs.h> 
Int obje_add(éree, parent, child) OBJECT *tree; int parent, child; 


obje_add is an AES routine that redefines a child object within an object tree; 
specifically, it redefines an object as being the offspring of a specified parent. 
tree points to the object tree being modified. child is the number of the object 
being redefined, and parent is the number of the object being made child's 
parent. 


obje_add returns zero if an error occurred, and a number greater than zero if 
one did not. 


See Also 
AES, object, TOS 


obje_change—AES function (libaes.a/obje_change) 
‘Change an object's state within a clipping rectangle 
#include <aesbind.h> 
include <obdefs.h> 
int obje_change(tree. object, junk, rectangle. newstate, redraw) 
OBJECT “tree; int ob ject, junk, newstate, redraw; Rect rectangle: 


objc_change is an AES routine that changes the state of an object within a 
named clipping rectangle. tree points to the object tree being modified, and ob- 
Ject ig the number of the object within the object tree. junk is reserved, and 
‘must be zero. 


rectangle is the clipping rectangle being used. It is of the type Rect, which is 
defined in the header file aesbind-h, Rect consists of four elements: 
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x X coordinate of rectangle 
y  Y coordinate of rectangle 
w width of rectangle 
h height of rectangle 
state indicates the new state for the object, as follo 
0x00 normal 


Ox01 selected 

0x02 cross-hatched 
0x04 checked 
0x08 disabled 
Oxt0 outlined 
0x20 shadowed 


Finally, redraw indicates whether or not to redraw the object being modified: 
zero indicates not to redraw, and one indicates redraw, 


‘obje_change returns zero if an error occurred, and a number greater than zero 
if one did not, 


See Also 
AES, object, TOS 


‘obje_delete—AES function (libaes.a/obje_delete) 


Delete an object from an object tree 

#include <aesbind.h> 

winclude <obdefs.h> 

int obje_delete(trce, object) OBJECT "tree; int object; 


obje_delete is an AES routine that deletes an object from an object tree. tree 
points to the object tree being modified, and object is the number of the object 
within the object tree. obje_delete returns zero if an error occurred, and a 
number greater than zero if one did not. 


See Also 
AES, object, TOS 


obje_draw—AES function (Iibaes.a/obje_draw) 
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Draw an object 

#include <aesbind.h> 

include <obdefs.h> 

int obje_draw(iree, object. depth, rectangle) 
OBJECT ‘tree; int object, depth; Rect rectangle; 
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obje_draw is an AES routine that draws an object. tree points to the object 
tree that contains the object in question. object is the number of the object 
within the object tree. depth indicates how many levels deep the object should 
be drawn: zero, draw only the object itself; one, draw the object plus its 
children; two, draw the object and its children and grandchildren; through eight 
(which is called MAX_DEPTH in obdefs.h), which draws the object and all of 
its descendents. Thus, setting object to zero (the root object within the tree) 
and setting depth to MAX_DEPTH will draw the entire object. 


rectangle defines the clipping rectangle to be used in drawing the object, It is 
of the type Rect, which is defined in the header file aesbind.h. Rect consists of 
four elements: 

x X coordinate of rectangle 

y  Y coordinate of rectangle 

w width of rectangle 

h height of rectangle 


obje_draw returns zero if an error occurred, and a number greater than zero if 
‘one did not. 

Example 

For an example of this routine, see the entry for object. 

See Also 

‘AES, object, TOS 


obje_edit—AES function (libaes.a/obje_edit) 
Edit a text object 
#inelude <aesbind,h> 
#include <obdefs.h> 
int obje_edit(tree, object. character, oldindex, kind, &newindex) 
OBJECT “tree; int object. character. oldindex, kind, newindex; 


obje_edit is an AES routine that edits a text object within an object tree. The 
object being edited must be either of type G_TEXT or G_BOXTEXT. tree 
points to the object tree that contains the object being edited, and object is the 
number of that object within the tree. character is the character to be inserted 
into the text. oldindex is the index of the character being replaced. kind is the 
type of replacement you want performed, as follows: 

0 Reserved 

1 Move input text into template; turn on cursor 

2 Compare input with validation string; update text; display string 

3 Turn off cursor 
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newindex is the index of character that follows the one edited. This value is set 
by AES. 


obje_edit returns zero if an error occurred, and a number greater than zero if 
one did not. 


See Also 
AES, TOS 


find—AES function (libaes.a/obje_find) 

Find if mouse pointer is over particular object 
Winclude <aesbind.h> 

#include <obdefs.h> 

int obje_find(tree, object. depth, mousex, mousey) 
OBJECT *tree; int object, depth, mousex, mousey; 


obje_find is an AES routine that finds whether the mouse pointer is positioned 
over a particular object. tree points to the object tree that holds the object in 
question, and object is its number within the object tree. depth is the depth to 
which the object tree should be searched, as follows: zero, search only for ab- 
Jject, one, search for object and its children; two, search for the object plus its 
children ‘and grandchildren; through eight (which is called MAX_DEPTH in 
obdefs.h), which searches for the object and all of its descendents. obje_find 
returns the number of the object over which the mouse pointer was found fo be 
positioned, or -1 if it was found not to be positioned over any requested object. 


See Also 
AES, object, TOS 


order—AES function (libaes.a/obje_order) 
Reorder a child object within the object tree 
include <aesbind.h> 

include <obdefs.h> 

int obje_order(tree, object, newposition) 
OBJECT “tree; int object, newposition; 


obje_order is an AES routine that moves a child object toa new position within 
the object tree. sree points to the object tree that holds the object to be moved, 
and object is its number within the object tree. newposition gives the new posi 
tion for this object in the list of its siblings: zero indicates the bottom of the 
list, one indicates one from the bottom, and so on; -1 indicates the top of the 
list. obje_order returns zero if an error occurred, and a number greater than 
zero if one did not. 
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See Also 
AES, object, object, TOS 


obje_set—AES function (libaes.a/obje_set) 
Calculate an object's absolute screen position 
include <aesbind.h> 
int obje_set(tree, object, &xcoord, &ycoord) 
OBJECT “tree; int object, xeoord. yeoord; 


obje_set is an AES routine that returns the absolute position on the screen of a 
given object. tree points to the object tree that holds the object in question, 
and object is its number within the tree. xcoord and ycoord give, respectively, 
the X and Y coordinates of the object; these are set by AES. obje_set returns 
zero if an error occurred, and a number greater than zero if one did not, 


See Also 
AES, object, TOS 


Notes 
Other sets of bindings call this routine obje_offset. 


object—Definition 
‘An object is an AES data form that encodes an element to be displayed on the 
screen. An object can be a rectangle, a text string, a box, a bit-mapped picture, 
a combination of any of these, or (most importantly) a number of such elements 
linked together in the form of an object tree. 


The object tree 

An object tree is a group of visual elements that are linked together to form a 
tree, One object is the tree's root object; it can have one or more child objects 
and each child object can have one or more siblings and children. 


Consider the following example, for the object tree foo. Like all object trees, 
foo has a root object, fool0|. This object, in turn, has three children: fool1!, 
fool2|, and fool3]. Each of these three children has two siblings; e.g., fool2l's 
siblings are fool1] and fool3]. Each of these children can, in turn, have its own 
children, each of which can have siblings and children of its own, 


‘As you can see, the name foo points to an array of objects; each object's sub- 
script depends on the order in which it is read into memory. If you wish to 
write an object tree by hand, it is up to you to know each object's subscript in 
order to write the tree correctly. 


Each object within the tree contains three “pointers” in its description. These 
are not true C pointers (i.e., memory addresses), but integers that are used by 
the AES to orient each object within its tree. The first pointer, next, points to 
the object's next sibling. For example, the next pointer for fool1] is 2, which 
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points to fool2I. If an object is the last of its siblings or if it has no sibling 
then mext must point to the object's parent object. The only exception is the 
root object, which has no sibling and no parent; its next pointer is always set to 
=1. The second pointer and third pointers, head and tail, point respectively to 
the object's first child and its last child. For example, fool0] has a head pointer 
of 1, which indicates that fool] is the first of its children, and a tail pointer of 
3, which indicates that foo[3] is the last of its children. If an object has only 
one child, then the head and tail pointers must both point to it; and if an object 
has no children, then both pointers must be set to -1. Note, however, that if 
object 1's head is set to 2 and its tail is set to 7, this does not mean that objects 
3 through 6 are all children of object 1. It only means that the first of its chain 
of children is 2 and the last is 7; the members of object I's “family” are in- 
dicated by the next pointers of the children themselves. 

The OBJECT structure 

Each object in an object tree must be described with the OBJECT structure 
that is declared in the header file obdefs.h, This structure is declared as follows; 


typedef struct object 
« 


Int ob.nexts {1% object's next sibling */ 
{nt ob- head; 7 Wead of object's children */ 
TH 7 Wall of object's children #7 


Unstned int cb_type: 7 Type of abject *7/ 
Unstoned Int obo ee; 
\netoned {nt obostetez 


ong. ob spec; 
int ob 8; 
{nt ob_yi 7 coordinate of object */ 
int ob_width; 2 viet #7 
{nt ob_height; 7 WeSahe *7 
9 oBsect; 
An object, as can be seen, is built out of following 11 elements: 
ob_next The next pointer. 
ob_head The head pointer. 
ob_tail ‘The tail pointer, 
ob_type This indicates the object’s type. The different types of object 
will be discussed below. 
ob_fiags This field encodes one of a set of flags for the object. The 
allowable flags are as follows: 
0x000 NONE No flags selected 
0x001 SELECTABLE Selectable by user 
0x002 DEFAULT Default (e.g., for buttons) 
0x004 EXIT If selected, ends dialogue 
Qx008 EDITABLE —_ Editable by user (e.g., string) 
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ob_state 


‘ob_width 
ob_height 


0x010 RBUTTON Radio button 

0x020 LASTOB Last object in tree 

0x040 TOUCHEXIT Click once to end dialogue 
0x080 HIDETREE Hide object from searches 
0x00 INDIRECT Redirect to another object 


Not every flag applies to every type of object. Some flags are 
mutually exclusive, e.g., EXIT and TOUCHEXIT; both force an 
exit from a dialogue, but the former requires that the button be 
clicked twice and the latter requires only one click. 


This indicates the object's status, i.e., how the object is to be 
displayed, The status codes are as follows: 


0x00 = NORMAL. Normal display 

0x01 SELECTED _ Displayed in reverse video 

0x02 CROSSED Draw an *X’ in object; used with 
rectangles only 

0x04 CHECKED —_ Draw check mark next to object 

0x08 © DISABLED —_Draw in shading rather than solid 

Ox10 OUTLINED —_Draw border around object 

0x20 SHADOWED Draw shadow on object 


Note that this specification can be changed as the program runs; 
for example, in the specification in a menu object can change to 
indicate that the item is disabled or has been selected. 


The object's specification. This field, which is the only long 
field in the OBJECT structure, can hold a pointer to a string, a 
pointer to a structure, or a bit map, depending on the type of 
object being described. Which specification belongs with which 
object will be described below, 

X coordinate of the object. In the root object, this value is an 
absolute value, in rasters; for each subordinate object, this value 
is relative to the X value of its parent. This allows the entire 
object tree to be repositioned on the screen simply by redefining 
the X coordinate of the root object. 

Y coordinate of the object. In the root object, this value is an 
absolute value, in rasters; for each subordinate object, this value 
is relative to the Y value of its parent. 

The object’s width. Thisis always an absolute value, 


The object’s height. This is always an absolute value. 


Types of objects 
The following table lists the available types of objects. As noted above, each 
type of object used the field ob_spec in a different way; the specification is 


also given: 
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G_BOX Draw a rectangle on the screen. The field ob_spec holds a bit 
‘map that describes the box's color and the thickness of its bor- 
der, as follows: 


high word The high byte is not used. The low byte holds 
the thickness of the border, from -127 to 127. 
Negative numbers draw the border outwards 
from the edge of the rectangle, whereas positive 
numbers draw the border inwards. 


low word The high nybble of the high byte holds the color 
of the interior of the rectangle, from one to 15, 
as follows: 


0 WHITE 

1 BLACK 

2 RED 

3 GREEN 

4 BLUE 

S CYAN 

6 YELLOW 

7 MAGENTA 

8 WHITE 

9 GRAY 
10 LRED 
1 
2 
2B 
14 
as 


LGREEN 
LBLUE. 
LCYAN 
LYELLOW 
LMAGENTA 


The names in capital letters are mnemonics that 
are defined in the header file obdefs.h; this 
means that you can use these mnenomics in your 
program, without having to remember the 
numeric code of each color, 


The low nybble of the high byte encodes the 
color of any text shown, as above. 


In the low byte, the first bit of the high nybble 
indicates whether or not the object shovid be 
transparent; zero indicates that the object is 
transparent and one indicates that it is not. The 
next three bits hold the fill pattern, from zero 
through seven. Zero indicates hollow: seven in- 
dicates solid; and one through six indicate 
gradations of shading, with the higher numbers 
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G_BOXCHAR 


G_BOXTEXT 


indicating increasing darkness, 


Finally, the low nybble the low word indicates 
the color of the border, as above, 


To set a figure with a border width of one raster, 
an inside color of white, a text color of black, the 
transparent bit off, the fill pattern of solid, and 
the border color of black, use the following C 
cane 

(116) HI TECE12) | (BLACK «BD | (179 | C7 <4) [BLACK 


This translates into the hexadecimal number 
Ox101FI 


This draws a rectangle with a single character inside it, It is 
used for elements like the “fuller” button on GEM windows. 
‘ob_spec points to a string that must be only one character long. 


This draws a box and writes text inside it. ob_spec points to the 
structure TEDINFO, which is described below, 


G_BUTTON This draws a button, which AES handles in its usual manner. 


G_FTEXT 


‘ob_spec points to the string that is written inside the button. 


This draws a string on the screen that can be edited by the user 
in the form of a dialogue. This is demonstrated in the second 
example, below. ob_spee points to the structure TEDINFO, 
which is described below, 


G_FBOXTEXT 


G_ICON 


This draws an editable string, like G_FTEXT, but surrounds it 
with a box as well. ob_spec points fo the structure TEDINFO, 
which is described below. 


This draws an “invisible box” on the screen, This box is used to 

connect a number of elements without changing the appearance 

of the object. For example, if you wished to reverse a large sec- 

tion of the screen when an icon is clicked, you would overla: 

the icon with an invisible box sized to the dimensions of the area 
shen the icon was clicked, the enti 

Within the invisible box would be reversed, not just the 

self. ob_spec encodes the color information, as in G_BOX. 


This draws an icon on the screen, ob_spec points to the struc- 
ture ICONBLK, which is described below. 
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G_IMAGE This draws a user-defined shape on the screen. ob_spec points 
to the structure BITBLK, which is described below. 

G_PROGDEF 
This is an object defined by the programmer. ob_spec points to 
the structure USERBLK, which is described below 

G_STRING This writes a string. ob_spee points to the string being written, 


G_TEXT This writes formatted text on the screen. ob_spec points to the 
structure TEDINFO, which is described below. 


G_TITLE This is used to create a title on the menu bar. ob_spec points to 
the string to be written. As indicated above, four specialized 
structures are used by the set of objects: BITBLK, ICONBLK, 
TEDINFO, and USERBLK. 


The BITBLK structure 
The BITBLK structure is defined in the header file obdefs.h as follows: 


typedef struct bit_block 
€ 


int *bi_pdate; —_/* Points to bit map */ 


{nt bi se; 7% Width of bit map in bytes #7 
int BILAL; 7* Weight in Lines */ 
int bioat ‘ Source X in bit form */ 
int biy: (7% Source ¥ in bit form */ 
int biceolor; —_/* olor of bit */ 
> piTeux: 


bi_pdata points to an array of integers that encode the object's bit map. bi_wb. 
gives the width of the bit map, in bytes. Note that the value of this variable 
‘must be even, to align along word boundaries. bi_hl gives the height of the bit 
map, in rasters, bi_x and bi_y give, respectively, the X and Y coordinates of 
the bit map. Finally, bi_color gives the object's color, encoded as above. 

The ICONBLK structure 

‘The structure ICONBLK is defined in the header file obdefs.h as follows: 
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typedef struct feon_ block. 
€ 
it "Tb pmask; —_/* Points to icon mask *) 
int *ibpdataz ——/* Points to icon deseription */ 
char *ib_ptext; /* String to appear in icon #/ 
int 7 Character to appear in jean */ 
int X Location of character */ 
nt ib Y location of character */ 
int ib X Location of icon */ 
int 1B) Y Location of Yeon */ 
int ibs \idth of icon */ 
int 11 HeToht of feon #7 
int 1b 7X location of text */ 
int ib) Y location of text */ 
int ibs 7 Width of text */ 
ine 16. 7 Weight of text */ 
> reowaus 


tb, pmask points to an array of integers that describe the icon mask. ib_pdata 
points to an array of integers that describe the icon itself. ib_text points to a 
string to be written into the icon; b_char points to a single character to be 
drawn on the icon. tb_xchar and Ib_ychar give, respectively, the X and Y 
coordinates of the character, ib_xicon, ib_yicon, ib_wicon, and ib_yicon give, 
respectively, the X coordinate, the Y coordinate, the width, and the height of 
the icon; and ib_xtext, ib_ytext, ib_wext, and ib_htext give, respectively, the 
X coordinate, the Y coordinate, the width, and the height of the text string 
within the icon. 


The TEDINFO structure 
This structure is used to create an editable dialogue. It is defined in the header 
file obdefs.h as follows: 


typedef struct text_edinto 
« 

ong te_ptext; Points to text */ 

long te_pempl ts Points to template */ 

long te_pyalid; Points to validation chars */ 

int : Foot */ 

int ten dunk werd *7 

int tej dust fication */ 

ine Color #7 

int ten dunk weed */ 

int ten Border thickness */ 

int tetatlen; Length of text string */ 

int te_tmplen; Length of tenplate string */ 
> veDtwFo; 


te_ptext points to a string to be displayed within the object. The text typed by 


the user will be written over this string. If you do not want text to be dis- 
played, replace it with a string of *@" characters as long as the maximum length 
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of the string to be input. 


te_ptmplt points to a template that will be used to input data. The template 
consists of a prompt, plus a string of underbar characters that is as long as the 
maximum length of the string that the user can input, The following is an ex- 
ample of a template string: 


ENTER FILE NAME: 7 


te_pvalid points to a string of validation characters. This string must be as long 
as the string that the user can input. Each character input by the user is 
checked against its corresponding validation character to ensure that it is of the 
right type. The validation characters are as follows: 


9 All numerals, zero through nine 

8 All alphabetic characters plus space 

8 Alphabetic characters, numerals, space 

p Valid TOS path name characters 

‘A Upper-case alphabetic characters plus space 

N — Upper-case alphabetic characters, space, numerals 

F TOS file name characters, question mark, asterisk, colon 
P TOS path name characters, question mark, asterisk, colon 
X Anything 


Note that use of any validation character besides F or X will cause a catastrophic 
system error. 


font indicates which font you want. te_Junkl and te_junk2 are reserved; 

can be set to any value, te_just indicates how you want the text to be j 
; TE_LEFT indicates left justification; TE_RIGHT, right justification; 
;_CNTR, centering, te_color indicates the color of the object; the color 
codes are the same as for G_BOX. 


te_thickness is the thickness of the border; it uses the same values as G_BOX, 
Finally, te_txtlen and te_tmplen give, respectively, the length of the user input 
string and the length of the template, each in bytes. The length of each should 
be one byte longer than the strings pointed to by te_ptext and te_ptmplt, to 
allow the addition of the NUL character at the end of each, 

The USERBLK structure 

‘The USERBLK structure can also be called the APPLBLK or APPL_BLK 
structure in other bindings. It is defined in the header file obdefs.h as follows: 


typedef struct user_blie 
€ 


ong ub.coce; —_/ points to user's code */ 
ong ub_parm; —_/* points Xe parenerer */ 
9 USERBLES 
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This structure allows the programmer to define her own object or routine; 
ub_code points to the routine in question, which can be specialized code writ- 
ten in C or assembly language to do specific tasks beyond the scope of the nor- 
mal AES routines. ub_parm points to the parameter to be passed to the routine 
named in ub_code. To use this structure, a programmer must have a sophis- 
ticated grasp of the AES. 


Designing objects 

Designing an object by hand is difficult. If possible, you should use a resource 
construction set (RCS) in designing screen elements, however, it is best to know 
how to modify the output of the RCS in order to gain exactly the results you 
want, 


Before beginning, you should do the following: First, draw a picture of the ob 
ject on graph paper. For text, each cell on the graph paper can considered 
equivalent to one character cell, i.c., the space taken up by one standard charac- 
ter on the screen (in high resolution, 9 character is eight rasters wide by 16 
high; in medium resolution, it is eight rasters wide by eight high; and in low 
resolution, it is four wide by eight high). Otherwise, each cell can be con~ 
sidered equivalent to a pixel. Drawing the picture may seem tedious, but will 
save you time over trying to draw it “on the fly” on the screen, 


Second, draw a “geneological table” of all the objects within the object tree. 
This will ensure that you set the next, head, and tail pointers for each object 
correctly. An example of such a table appears in the entry for menu, 


Examples 

‘The first example draws a set of seven nested rectangles on the screen. Typing 
any key returns you to msh, Note that all objects are sized in rasters, for a 
high-resolution screen, 


Winelude <aesbind.n> 
#ine\ude <obdets.h> 
Hinelude <gendets.> 
sksetine SPECT OxI00FIL 
P 
(1 <2 18) | order 1 raster thickd 
(WHITE << 12) | Gorder color; WHITE = 02 
(WAITE << 8) |) [Text colors 
<7) | Turn on replace) 
7 <<) | fo e114 tone motel) 
BLACK. 
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‘define SPECZ Oxt11FOL 


Vi 
* Lest (1 ce 16) | Ghorder $ raster thick 

* (BLACK << 12) | [Border color] 

* (BUCK ce 8) | KText color 

Py << 7) | Crum on replace? 

. (7 <4} | —_TFIUL pattern to solid) fone nybbtel? 
. aITE: {FTL colord 

” 


opuecr fitia = ¢ 
/*  next/nesd/tail/type/ flags / state /specif./ XY Su LH 47 

“1, Ny Te GOK, DEFAULT, NORMAL, SPECI, 0, 0, 639, 399, 

0, 2) 2) G.BOK, DEFAULT, NORMAL, SPEC2, SD, 30, 539, 339, 

1,3) 3, 680K, DEFAULT, NORMAL, SECT, 50, 30, 439, 279, 
NORMML, SPEC, 50, 30, 339, 219, 
NomMAL; SPECI, 50, 30, 239, 159, 
NORAAL, SPEC, 50, 30, 139, 99, 
NORMAL; SPECI, 50, 30, 39, 39 


X, ¥ are absolute for root object; for all others, XY 
elative to the parent object. W& K are absolute for all object 
* ALU values in rasters; calculated for high-resolution sereen. 

u 


mained € 
fnt nowhere = 0; 1* For unused pointers #7 
appl_inite 11 Beain application */ 
‘graf_mouse(H OFF, Enowhere); 79 Turn off mouse pointer */ 
obje_draw(#itl, ROOT, MAX DEPTH, 0, 0, 639, 3999; 
cevnt_keybdd: 71 Wait for keybd event */ 
graf _mouse(X_ON, Enowhere); 7 Turn on mouse pointer */ 
appl_exit: 7 Exit from application */ 
exitto); 

> 


‘The second example presents a brief dialogue, and demonstrates the TEDINFO 
structure. Note that all objects are sized in rasters, for a high-resolution screen, 
Hinelude <aesbind.h> 
Hinelude <abdefs.h> 
Hinelude <gemdefs.t> 
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bs 
* (5 << 16) | (order 5 rasters thick) 
(BLACK << 12) | Border color; BLACK = 11 
. (WHITE cc 8) | TText color; WEITE = 0} 
+ <7) | Turn on replace bit) 
. (7 << 4) | {FILL pattern soli] tTopether one nytinte) > 
* Lack (FILL color 
” 
‘idofine BIFLAGS 0x5 (Toes SELECTABLE | EXIT #7 
define B2FLAGS 037 YP Net SELECTABLE | OBTAULT | EXIT +7 


/* Strings and structure used with dialogue */ 
‘cher input) = Nagaasaaaaa; 

char template] = "YOUR NAME: % 
char check{] = "FFFFFFFFFE"; 

char buttont C1 = Hox; 

char button@ (= "EXIT"; 


TEDINFO text) = ¢ 
74 polnter to text (13! indicates no kext) 
+P pointer to text template 


+ | "| pointer te validation string 

tT] | | font enie character 

si | reserved integer (tates anything) 

* 1 | | | | dastifieation code character 

DE bP LT eter cae 

“| 1 LL | | reserved integer Ceakes anything? 
=} 1 fF TE 1 | [border thickness (rasters) 
stot FEEL 1 Lp tree string ceherss 

=} 1 1 LE LL LD Peemplate string (chara) 
"vooyovovV¥ oy ovwvvy a 

rout, template, check, 184, 1,TE_CVTR WAITE,5,1,11,22 


7 


flags. / states specif. X/ 1/ Wy H*/ 
“1, 3, BOK, NOME, NOBWAL, SPEC, 0, 0, 600, 250, 
2, -1) +1, GLFTEXT, EDITABLE, NOMMAL, text, 100, $0, 600, 100, 
“Te oT GBUTTON, BIFLAGS, NOMMAL, buttont, 230, 200; 20, 20, 
2, +1, -1, @BUTTON, BZFLAGS, NORMAL, button2, 300, 200, 40, 20 


23 


7 Rectangles used in ensuing traces */ 


Rect tenpbex 
Prect terpotr 


8, 0, 0, 09; 
 dtempbox.x, Btespbox.y, Stenpbex.w, btembox.h ); 
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main ¢ 
int nowhere = J For orphaned pointers */ 
int quit; 
char newstring (29) = “TOUR MINE 1S 
appl_inito; 74 Begin application */ 
graf_mouse(ARRON, Enovhere); /* Mouse ptr. to arrow */ 


form.center(diatogue, tenpetr); _/* Center dialogue box */ 
form-dial(O, 1, 1, 1, 1, ember); /* Get screen ares */ 
fora 414, 1, 1) tenpbond; /* Star wars" effect */ 
oble_draw(dialogue, ROOT, NAL DEPTS, cempbox): 

‘Draw dialogue object */ 


for G22) € 
‘lt = form dotdiatogse, 1): 
Te cquit se 2) € 
Streat(newateing, Snput)y 
strepy(template, nevatr ina); 
bje-drau(dialogue, ROOT, MAX DEPTH, Yenpbox); 


5) 


if (quit = 3) ¢ 

NCR, 1, 1, Ty 1, empboxd; 
UGS, 1, 1, 1, 1, tempbon; 
oppl_exit? 
exit0y; 


> 
> 

See Also 

AES, menu, obdefs.h, TOS, window 


object format—Definition 
‘An object format describes the form of compiled program that still contains 
relocation information. The linker Id reads file in object format to create ex- 
ecutable files. 


Mark Williams C creates object modules that are in the format n.out, which 
differs somewhat from other formats used on the Atari ST. 


See Also 
Id, n.out 


od—Command 
oid [-bedox] [file] [ [+] offsed-IIb1 
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Offgivit 


od prints the specified file as a sequence of octal numbers, or machine words, 
If no file is specified, od dumps the standard input, 


‘The following options allow the user to select the output format: 


-b bytes in hexadecimal 

-€ bytes in ASCII characters 
-d_ words in decimal 

-o words in octal 


Dumping can start at offset into the file, The specified offset is octal unless 
the *." suffix is present to signify decimal. The offset is in bytes unless the b 
suffix is present to signify 512-byte blocks. 


See Also 
ASCII, commands, db, msh 


Off gibit—xbios function 29 (osbind.h) 
Clear a bit in the sound chip's A port 
#include <osbind.h> 
#inelude <xbios.h> 
void Offgibit(mask) char mask; 


Offgibit manipulates the sound chi 
‘This port controls the disk drives, 


Offgibit reads the contents of register A; it then ANDs this value with mask; 
and it writes the result back into register A. The bits in this register are bound 
to various control lines within the Atari ST, For a table of which bits bind 
which lines, see the entry for Ongibit. 

Example 

The following example demonstrates Ongibit and Offgibit; 


Winelude <osbird.h> 


's register A (also called the “A port’ 


maint) ¢ 
Unsigned char a; 


Ceonuscvait for both floppy drives to stop and type # key\r\n"; 


eeined; 

a= Giaccess(a, 14); /* save the original value... */ 
Oftaibiecoxt9y: P* turn off bits 1 and 2 */ 
CeonscBath Floppy drive Lights en...\n\r, 

cecingas 
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Onaibit¢ox02); (7 turn on bit 147 
Cconws("Orive A Light off...\n\eez 
cneeingy 


Ongtbie x06); 


tof 


Giaceess(a,0x80|14); (/* restore original contents */ 
Perm; 

> 

See Also 

Giaccess, Ongibit, TOS, xbios 


‘Ongibit—xbios function 30 (osbind,h) 
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Turn on a bit in the sound chip's A port 
#include <osbind.h> 

#include <xbios.h> 

vold Ongibit(mask) char mask; 


Ongibit manipulates the sound chip's register A (also called the “A port"). 


Ongibit first reads the contents of register A; it then ORs with mask; and fin- 
ally it writes the result back into register A. 


‘The bits in ropiater A are bound to various control lines within the Atari ST, a 
‘allows: 


0 side of the floppy disk (0/1) 
1 drive A (selected when clear) 
2 drive B (selected when clear) 
3 RS-232 request-to-send (RTS) line 
4 RS-232 data-terminal-ready (DTR) line 
5 Centronics data strobe 
6 general purpose output (GPO) on video connector 
7 unused 
number should be set the bit that corresponds to the desired line. 
Example 
For an example of this function, see the entry for Offgibit. 
See Also 
Giaccess, Offgibit, TOS, xbios 
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open—UNIX system call (libe.a/open) 
Open a file 
open(file, (ype) char *file; int type; 


‘open prepares a file to be written into, or to have its data read, When success- 
ful. open returns a file descriptor, which is a small, positive integer that iden— 
tifies the open file for subsequent calls to read, write, close, dup, or dup2, The 
type argument can be set to zero for reading, one for writing, or two for both 
reading and writing. After a file is opened, reading or writing will begin at 
byte 0. 


Example 
This example copies argy[1] to argwi2] by using UNIX-style routines, It 
demonstrates the functions open, close, read, write, and creat, 


Hinelude <stdio.h> 
fisetine BUFSIZE (20°512) 
char buf IBUFSIZES 


imaincarge, argv) int argc; char *argvil; ¢ 
register Int 16, of6; 
register unsigned int n; 


if Carge |= 3) 
fatal(*Usage: copy source destination"); 
Af (itd = opancaraveta, 09) == 1) 
faral(reannot open input file); 
If (Gofd = creattargvt2}, 09) == -1) 
fatal(tcannot open output fle"); 
while (n= read(ifd, buf, SUFSIZED) |= 0) ¢ 
Hf (oes 1) 
fatal read error); 
ff (wettecotd, buf, n) I= ny 
faral elte error 
> 
if (elosecifé) == -1 || closetofa #= -1) 
facalcreannet clos 
exit(o); 


als) char 5; 


fprintf(stderr, copy: Xe\n", 5); 
exit: 


See Also 
STDIO, UNIX routines 
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Diagnostics 

open returns -1 if the file is nonexistent, or if a system resource is exhausted. 
Notes 

open is a low-level call that passes data directly to TOS. It should be inter- 
mixed cautiously with high-level calls, such as fread, fwrite, or fopen. 


operator—Definition 
An operator relates one operand to another. For example, the statement 


2 


relates 1 and 2 through the operation of addition; on the other hand, the 
statement 


fey 


relates A and B logically, by asserting that the former is greater than the latter; 
whereas 


aa 


relates A and B by assigning the value of the latter to the former. The 
following is a table of C's operators: 


. multiptication 

L division 

% 

+ 

- subtraction 

< less than 

<= less than or equal to 
> greater than 

>= greater than or equal to 
&& logical AND 

l= inequality 

i logical negation 

i logical OR 
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assiga 
increment and assign 
decrement and assign 
multiply and assign 
divide and assign 
‘modulo and assign 


increment 
decrement 

== equivalence 

& bitwise AND 


bitwise exclusive OR 
I bitwise inclusive OR 


<< shift left 
> shift right 
* indirection 


render an address 
function indicator 
array indicator 
structure pointer 
structure member 

h conditional expression 


See Also 
precedence, sizeof 
The C Programming Language, page 49. 


osbind.h—Header file 
#include <osbind.h> 


osbind.h is a header file that declares the functions bios(), gemdos(), and 
xbios(), It also defines numerous macros that ease the use of these functions. 
‘The text of osbind.h is included with your copy of Mark Williams C. 


See Also 
bios, gemdos, header file, xbios, TOS 
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path—Definition 


A path is the full name of a file, including the names of all the directories 
within which it resides. Conventions for naming paths vary among operating 
systems; for example, the file foobar that is in the directory computer that, in 
turn, is owned by user anne could be listed as follows under the COHERENT 
system: 


‘Lest /anne/compater/ foobar 
but as follows under MS-DOS or TOS: 
cconputer\focbar 


‘The latter two operating systems do not use user names in constructing the path 
name. Note, too, that MS-DOS and TOS use the backslash ‘\’ rather than the 
slash '/" to separate the elements of a path name. 


See Also 
directory 


PATH Environmental parameter 


PATH names directories that msh searches when looking for files that you have 
asked it to execute. For example, typing 
eteny PATH.bin, \Bin, ,\UIB 


tells msh to search for executable files first in its set of built-in commands (as 
indicated by .bin), then in the directory \bin, then in the current directory (as 
indicated by the two commas with nothing between them), and finally in the 
directory lib. 


It ig set with the seteny command. 


See Also 
msh, seteny 


patterns—Definition 


pattern is any combination of ASCII characters and wildcards that can be in- 
terpreted by a command. 

See Also 

egrep, wildcard 


peekb—Library function (libe.a/peekb) 
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Extract a byte from memory 
int peekb(5p) char *bp; 
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peekb examines an arbitrary location in memory. It reads a byte located at the 
address bp. peekb circumvents the system's memory protection by temporarily 
entering supervisor mode. 


See Also 
peekl, peekw, pokeb, pokel, pokew 


peckl—Library function (libe.a/peekl) 
Extract a long from memory 
long peekI(/p) long */p; 
peekl returns the long (four bytes) at /p. peekl circumvents the system’s 
niemory protection by temporarily entering supervisor mode. 
See Also 
peekb, peekw, pokeb, pokel, pokew 
Notes 
peek! does not test for odd addresses, and will generate a bus error if given such 
‘an address. In general, be careful about what you peek and poke. 


peekw—Library function (libe.a/peekw) 
Extract a word from memory 
Int peekw(wp) int *wp; 


peckw returns the word (two bytes) at wp. peekw circumvents the system's 
memory protection by temporarily entering supervisor mode. 


See Also 
peekb, peekl, pokeb, pokel, pokew 


Notes 
peekw does not test for odd addresses, and will generate a bus error if given 
such an address, In general, be careful about what you peek and poke, 


petror—General function (libe.a/perror) 
System call error messages 
#include <errno.h> 
perror(siring) 
char “string; extern int sys_nerr; extern char *sys_errlist[ Js 


error prints an error message on the standard error device. The message con- 
sists of the argument string, followed by a brief description of the last system 
call that failed. The external variable errno contains the last error number. 
Normally, string is the perror of the command that failed or a file perror, 
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‘The external array sys_errlist gives the list of messages used by perror, The ex- 
ternal sys_nerr gives the number of messages in the list. 


See Also 
erro, errno.h, error codes 


Pexec—gemdos function 75 (osbind.h) 
Load or execute a process 
‘#include <osbind.h> 
long Pexec(mode, path, tail. env) int mode ; 
char “path, *tail, *eny; 


Pexec loads or executes a process. mode equals zero if the process is to be 
loaded and executed, or three if the process is to be loaded but not executed; 
the latter mode is used with overlays. path points to the path name of the file 
to be loaded; it must be a NUL-terminated string. ‘ail points to the command 
tail, which included redirection information. env points to a block of strings 
that define the environment, Esch string must terminate with a NUL character, 
and the block as. whole must terminate in NULL. 


If mode equals zero, Pexee returns the child process's exit status when the child 
process exits; if mode equals three, it returns the address of the base page of the 
loaded process. In either instance, it returns a negative error code if it cannot 
load the process. 


Example 
‘This example times the execution speed of a program. It also demonstrates the 
time function clock, 


Winelude <ombind.h> 
Hinelude <time,h> 


main(arge, argv) 
int arge; char "arava; 
« 


char progrant&0i; 
char coomand(256) ; 
int x 

clock_t timer; 
int stat 


if Garge € 2) € 


PrintfcMuage: tise comand f ares... 1\W'): 
exited: 
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iner = clock; 
status = Pexec(®, program, comand, *PATAE\O"D; 
timer = clocked * timers 
printf("kld.X0SLd seconds\n", 
Pimer/CL€ TK, (eimerZCUx_Ter) * (1000/cLx TOK); 
return status; 
> 


See Also 
argy, gemdos, TOS 


Physbase—xblos function 2 (osbind.h) 
Read the physical screen's display base 
#include <osbind.h> 
wlnclude <xbios.h> 
Tong Physbase() 


Physbase reads the physical screen's display base, and returns a pointer to the 
display base. The physical screen base is the location in memory currently dis- 
played. 


For examples of this function, see the entries for Logbase and Priblk. 


See Also 
Loghase, Setscreen, TOS, xbios 


picture—Example 
Format numbers under mask 
double picture(number, mask, output) 
double number; char *mask. “output; 


picture uses a mask to format a double-precision number; it returns any over 
Flow. It is designed to be used with accounting programs, and other utilities 
that require precise formatting of printed numbers. 


picture formats a given number by using a mask string. The mask may contain 
any characters; however, only a few have special significance, Non-special 
characters in the mask body are printed if, during execution, they come to be 
preceded by one or more numerals. Trailing non-special characters print if the 
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displayed number is negative. 
The following lists the special characters that contro! formatting within a mask: 


9 


Provides a slot for a number. For example, $ with mask 999 CR gives 
005<sp><sp><sp>, whereas printing -5 with mask 999 CR gives 005 CR. 
Note that ‘C’ and 'R’ are not special characters, but are taken literally. 


Provide a slot for a number, but supress leading zeroes. For example, 
printing 1034 with mask ZZZ,ZZZ gives <sp><sp>1,034, Note that the 
comma is not a special character, 


Provide a slot for a number, but shrink out leading zeroes, For example, 
printing 1034 with mask JJJ,JJJ gives 1,034. 


Provide a slot for a number, but shrink out any zeroes, For example, 
printing 070884 with mask K9/K9/K9 gives 7/8/84. 


Float a dollar sign to the front of the displayed number. For example, 
printing 108 with mask $Z,ZZZ gives <sp><sp>S105. 


Separate the number between decimal and integer portions. For example, 
printing 105.67 with mask ZZZ.999 gives 105.670. 


Provide a slot for a number, but supress trailing zeroes. For example, 
printing 105.670 with mask ZZ9.9TT gives 105.67<sp>. 


Provide a slot for a number but shrink out trailing zeroes. For example, 
printing 108.600 with mask ZZ9.9SS gives 105.6. 


This character, if placed to the left of the mask, floats to the front like 
the ‘S', but only if the number is negative. For example, printing 105 
with mask -Z,ZZZ gives <sp><sp>105, whereas printing -108 gives 
<sp><sp>-105. 


This character acts like the minus sign ‘-', but prints a ‘('. For example, 
printing 105 with mask (ZZZ) gives whereas printing ~5 gives 
-<sp><sp>(5). 


If placed to the left of the mask, this character floats to the front like the 
minus sign ‘-', but is replaced by a ‘-" if the aumber is minus. 
ample, printing 5 with mask +ZZZ gives <sp><sp>S+, whereas printing -5 
gives <sp><sp>-S. Placed tehind the mask, it is printed if the number is 
positive, but is replaced by a minus sign *-' if the number is negative. 
For example, printing $ with mask ZZZ+ gives whereas printing -5 gives 
<sp><sp>5-. 


When placed to the left of the mask, this character fills all leading spaces 
to its right, For example, printing 104.10 with mask *ZZZ,ZZZ.99 gives 
9104.10, and printing 104.10 with mask *SZZ,ZZZ.99 gives 
"$104.10. 
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See Also 
commands, STDIO 


Diagnostics 
picture returns all overflow as a double. For example, attempting to print -1234 
with mask (ZZZ) gives (234) and returas ~1, 


Notes 
For the source code of picture, see the file picture.c, 


pnmatch—General function (libe.2/pnmatch) 
Match string pattern 
int pamatch(string, pattern, flag) 
char *string, *pattern; int flag; 


pumatch matches siring with pattern, which is a regular expression, pnmateh 
roturns | if pattern matches string, and 0 if it does not, Each character in pat 
term must exactly match a character in string; however, the wildcards *',‘", ‘[, 
and ‘J’ can be used in pattern to expand the range of matching. The flag argu- 
ment must be either 0 or 1: 0 means that pattern must match string exactly, 
whereas | means that pattern can match any part of string. In the latter case, the 
wildcards ‘** and ‘S' can also be used in pattern. 


Example 
This example looks for pattern argy{1] in standard input or in file argv{2J. Tt 
demonstrates the functions pnmatch, fgets, and freopen. 


Hinelude <stdio.h> 
fHdoFine MAXLINE 128 
char but (MAKLINED; 


InainCarge, arg) int arge; char *argvil; ¢ 
if (ange t= 2 Ab arge t= 3) 
fatal Usage: preatch pattern ( file 1%): 
if (arge == 3 Ab Freopentargvi2i, Yr", stdin) == MULL) 
fatal(cannot open input file"; 
While Cfgets(buf, MAKLINE, stdin) I= MULL) € 
if dprmatch(buf, ervclt, 199 
printf(mie, buf); 
2 
if (feotestdiny 
fatal read error); 
exitco 
d 


fatal(s) char *5: ¢ 
fprintf(stderr, prmatch: Xs\n", =); 
exten; 
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See Also 
egrep, msh, string 


Notes 
Slag must be zero or one for pnmatch to yield predictable results. 


pointer—Definition 
‘A pointer is a data type that consists of the address of another item of data; 
therefore, it is said to “point” to that item of data. 


‘The physical size of the pointer data type is determined entirely by the 
microprocessor. Pointers are 16 bits long on the i8086, SMALL model, non- 
segmented Z8000, and on the PDP-I1; they are 32 bits long on the i8086, 
LARGE model, segmented 28000, the 68000, and the VAX. 


Note that failure to declare a function that returns a pointer (most commonly, a 
char *) will result in that function being implicitly declared as an int, This will 
‘not cause an error on microprocessors in which an int and a pointer both have 
the same size; transporting this code to a microprocessor in which an int consists, 
of 16 bits and a pointer consists of 32 bits will result in the pointers being trun~ 
cated to 16 bits and the program probably failin; 


C allows pointers and integers to be compared or converted to each other 
without restriction, Mark Williams C flags such conversions with the strict 
message 


integer pointer pun 
and comparisons with the strict message 

Integer polnter eeapertsen 
‘These problems should be corrected if you want your code to be portable to 
other computing environments. 


Casting a pointer from one data type to another may result in the loss of preci- 
sion when alignment restrictions are taken into account. These sorts of data 
transformations should be done with great care to ensure that code remains 
portable. 


See Also 
data formats, declarations, pun 


pokeb—Library function (libe.a/pokeb) 
Insert a byte into memory 
int pokeb(ép, 5) char "bp; int 5; 
pokeb writes the character 6 at an arbitrary location bp in memory. pokeb cir 
cumvents the system's memory protection by temporarily entering supervisor 
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mode. pokeb returns its argument b. 


See Also 
peekb, peekl, peekw, pokel, pokew 


pokel—Library function (libe.a/pokel) 
Insert a long into memory 
Jong pokel(/p. !) long */p. I; 

pokel writes the long / (four bytes) at an arbitrary location /p in memory, pokel 

Brcumvents the system's memory protection by temporarily entering supervisor 
mode. 
See Also 
peekb, peekl, peekw, pokeb, pokew 
Notes 
pokel does not test for odd addresses, and will generate a bus error if given 
such an address, Tn general, be careful about what you peek and poke. 


pokew—Library function (libe.a/pokew) 
Insert a long into memory 
int pokew(wp, {) int *wp, w; 
pokew writes the word w (two bytes) at an arbitrary location wp in memory, 
pokew circumvents the system's memory protection by temporarily entering su- 
pervisor mode. 
See Also 
peekb, peekl, peekw, pokeb, pokel 
Notes 
pokew does not test for odd addresses, and will generate a bus error if given 
such an address, In general, be careful about what you peek and poke. 


Definition 
A port passes data to and receives data from remote devices, 


See Also 
aux:, felose, FILE, fopen, prn:, stream 


Portability—Definition 
Portability means that code can be recompiled and run under different com- 
puting environments without modification, Although true portability is an 
ideal that is difficult to realize, you can take a number of practical steps to en= 
sure that your code is portable: 
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1, Do not assume that an integer and a pointer have the same size, Remem~ 
ber that undeclared functions are assumed to return an int. If a function 
returns a pointer, declare it so. 


2, Do not write routines that depend on particular order of code evaluation, 
particular byte ordering, or particular length of data types. 

3. Do not write routines that play tricks with a machine's “magic numbers”; 
for example, writing a routine that depends on a file's ending with <ctrl- 
Zp instead Of EOF ensures that that code can run only under operating 
systems that recognize this magic number. 


4, Always use manifest constants, such as EOF, and make full use of 
#define statements. 
5. Use header files to hold all machine-dependent code. 


6, Declare everything explicitly. In particular, be sure to declare functions 
to void if they do not return a value; this avoids unforeseen problems with 
undefined return values. 


See Als 
#define, header file, manifest constant, pointer, pun, void 


pow—Mathematics function (libm.a/pow) 
Compute a power of a number 
include <math.h> 
double pow(=, x) double =, x; 


pow returns = raised to the power of x, or 2*. 


Example 

For an example of this function, see the entry for exp. 
See Also 

mathematics library 


Diagnostics 
pow indicates overflow by an errno of ERANGE and a huge returned value. 


pr—Command 
Paginate and print files 
pr [options| [file ..} 
pr paginates each named file and sends it to the standard output, The file name 
** means standard input. If no file is specified, pr reads the standard input. 


Each page has a header that gives the date, 
bers. pr may be used with the following options, 


name, and page and line num- 
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4 Skip the first n pages of each input file. 


<n Print the text in # columns. This is used to print out material that was 
typed in one or more columns, 


-h header 
Use header in place of the text name in the title. If header is more than 
‘one word long, it must be enclosed within quotation marks. 

‘Set the page length to » lines (default, 66). 

Print the texts simultaneously, in separate columns. Each text will be as- 
signed an equal amount of width on the page; any lines longer than that 
will be truncated. This is used to print several similar texts or listings 
simultaneously. 

Number each line as it is printed. 

‘Separate each column by the character c. You can separate columns with a 
letter of the alphabet, a period, or an asterisk. Normally, each column is 
left justified in a fixed-width field. 

Suppress the printing of the header on each page, and the header and 
footer space. 


Set the page width to m columns (default, 80). Text lines are truncated to 
fit the column width. The maximum width is 256 columns, 


Example 
To print a numbered listing of a text file, do the following: First, plug a printer 
into your Atari ST and turn it on. Second, type this command: 
pr -n filename >pen: 
where filename is the name of the file you wish to print. 


See Also 
commands, pra: 


brecedence—Definition 
Precedence refers to the property of each C operator that determines priority of 
execution; operators are executed in order of their degree of precedence, from 
highest to lowest. The order of precedence for operators is summarized on page 
49 of The C Programming Language. 
See Also 
operators 
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Format output 
+#include <stdio.h> 
printf(format [ , arg }...) char *formar; 


ff uses the format string to specify an output format for each arg, which it 
then writes on the standard output. printf reads characters from formal one at 
a time; any character other than a percent sign “%' or a string that is introduced 
with a percent sign is copied to the output directly, ‘%' tells printf that what 
follows specifies how the corresponding arg is to be formatted; the characters 
that follow ‘%' can set the output width and the type of conversion desired. 
The following modifiers, in this order, may precede the conversion type: 
A minus sign ‘-" will left-justify the output field, instead of the default” 
right justify. 
A string of digits gives the width of the output field. Normally, the field 
is padded with spaces to the field width; it is padded on the left unless 
left justification is specified with a‘-". If the field width begins with ‘0', 
field is padded with ‘0° characters instead of spaces; the ‘0° does not 
cause the field width to be taken as an octal number. If the width 
specification is an asterisk ‘*', the routine uses the next arg as an integer 
that gives the width of the Field, 


A period *,' followed by a string of digits indicates the precision, For 
floating point (e, f, and g) conversions, the precision is the number of 
digits printed after the decimal point, For string (s) conversions, the 
precision is the maximum number of characters used from the string, If 
ion specification is given as an asterisk “*", the routine uses the 
feger giving the precision. 
‘The letter ‘I’ before any integer conversion (d, 0, x, or u) indi s that 
the argument is a long rather than an int. Capitalizing the conversion ty 
has the same effect; note, however, that capitalized conversion types ar 
not compatible with all C compiler libraries. 


‘The following format conversions are recognized: 
Output a 6" character. No arguments are processed. 
© Convert the int argument to @ character. 
4 Convert the int argument to signed decimal. 
D Convert the long argument to signed decimal. 
€ Convert the float or double argument to exponential form. The format ist 


d.ddddddesdd, where there is always one digit before the decimal point 
and as many as the precision after it (the default is six). The exponent 


sign s may be either ‘+ or 
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U 
x 
x 


Convert the float or double argument to a representation with an optional 
leading minus sign *-', at least one decimal digit, a decimal point ('.’), 
and optional decimal digits after the decimal point. The number of digits 
after the decimal point is the precision (default, six). 


Convert the float or double argument to whichever of the formats d, e, or 
f loses no significant precision and takes the least space. 


Convert the int argument to unsigned octal. 
Convert the long argument to unsigned octal, 


‘The next argument points to an array of new arguments that may be used 
recursively, The first argument of the list is a char * that contains a new 
format string. When the list is exhausted, the routine continues from 
where it left off in the original format string. 


Output the string to which the char * argument points. Reaching either 
the end of the string, indicated by a NUL character, or the specified 
precision will terminate output. If no precision is given, only the end of 
the string will terminate 


Convert the Int argument to unsigned decimal 
Convert the long argument to unsigned decimal. 
Convert the int argument to unsigned hexadecimal, 
Convert the long argument to unsigned hexadecimal. 


Example 

‘The following example uses printf to print the location of the mouse pointer on 
the screen. The code \033H tells printf to output an <esc> character and the 
letter ‘H', which tells TOS to home the cursor. 


include <pendets.hy 
‘lnelude <aenbind.h> 


Hefine cuicKs 1 of clicks expected on mouse button */ 
‘define BUTTON 1 ich button; 1 = leftmost */ 

etine DOW 1 ive, the mouse button {8 down #/ 

1 throwaway declarations, to keep system fron scribbling over itself */ 


int nowhere © 0; 
Rect rorect = C0, 0, 0, 0 9; 


fons used by evnt_multiC) */ 

int selection; 71 code for event that occurred */ 
Unsigned int which = (MUXEYBD | MU_SUTTOND; 

int buffer ti; 7* place to write AES messages */ 
int mousex; 77 mouse X coordinate */ 

‘nt meusey; 7 mouse Y coordinate */ 


pra: 


prn:—TOS device 0 

TOS logical device for parallel port 
TOS gives names to its logical devices. Mark Williams C uses these names, 
allow the STDIO library routines to access these devices via TOS. pra: is th 
logical device for the the parallel port. 


Example 
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J* 0K, here ve 90 
appl_inite 
graf mouse(ARROW, Enavhere); 


forts3) € 


) 
> 


See Also 
fprintf, pute, puts, scanf, screen control, sprintf, write 


Notes 


Because C does not perform type checking, it is essential that each argument. 
match its specification in the format string. 


The use of upper-case format characters to specify long arguments is not stan- 
dard, g00 wil be phased out to eonforan with: the ANSE standard. Use thal 
modifier. 


7 


selection = evnt_multi(uhich, CLICKS, BUTTON, DOW, 


switen¢selection) ¢ 

case WL_KEYED: 
eppl_exitOz 
exit); 


case MY_BUTTON: 
Graf_mouse(M OFF, Anowhere); 
Print#C\OS3iK: KOS Y: O3d\n", mousex, mousey?) 
graf _mousecn OW, Enowhere); 
break; 

default: 
break; 

> 
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Binetude <stdio.t> 
rain 
FILE *fp, *fopent?: 
if (4B + fopentpens4, "9 t= RULL) 
fprint (fp, torn! enabled.\n") 
else printf(tpens cannot open.\n"); 
2 
See Also 
aux:, com: 


process—Definition é ; 
A process is a program in the state of execution. 


Protob{—xbios function 18 (osbind.h) 
Generate a prototype boot sector 
winclude <osbind.h> 
winclude <xbios.h> 
vold Protobt(buffer, serialno, type. flag) 
char *buffer; long serialno; int type, flag; 


Protobt generates a prototype boot sector, and returns nothing. bu/fer points to 
a 512-byte buffer; this buffer may already contain an image of a boot sector, 
but whether it does or not is irrelevant. serialno is a serial number that will be 
stamped into the boot sector; setting serialno to -1 leaves the boot sector's serial 
number unchanged, whereas setting it to any number higher than 0x01000000 
creates a random serial number that will be stamped into the boot sector. type 
is an integer that encodes the type of disk being worked with, as follows: 


0 40 tracks, single sided 

1 40 tracks, double sided 

2 80 tracks, single sided 

3 80 tracks, double sided 
Setting (ype to -1 retains the current disk type. 
Finally, flag indicates whether the boot sector is executable or non-executable: 
zero indicates executable; one, non-executable; and -1, retain the current type. 
Example 
For an example of how to use this macro, see the entry for Flopfmt. 


See Also 
TO: 
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Prtblk—TOS macro (osbind.h) 
Print a dump of the screen 
#include <osbind.h> 
#include <xbios.h> 
int Prtblk(p) struct prtblk *p; 


Prtblk is a macro that uses the TOS function xbios. It prints out a block of 
it returns 0 if the printing was successful, and nonzero if it was not. p 
points to a specialized structure, which is defined in the header file xbios.h. 


Prtblk can also be used to print text strings. 


Example 
This example demonstrates the functions Prtblk, Setprt, Physbase, Getrez, and 
Setcolor. 


Winctude <osbind.h> 
Winclude <xbios.h> 


fnaing € 
struct petbtk pb; 
int palette(tél; 
register int 1; 


2 Determine printer characteristics */ 
5 = Setpete-1)3 
if C1 & PR DAISY 
pb. pb_type = P8_DAISY; 
else if 1 & PR_WOKO) 
pb. po_type = PB_NONOIGO; 


clue if Ci 8 PRLEPSOND 
‘pb. pb_type = PB_MONOI20; 


pb.pb_type = PB_COLORIED; 


pb.pb_port = (iE PR_SERIAL) ? PRLAUX + PB_PR 
po.pbdstres = (1 & PR_FINAL) 7 PB_FINAL : PS DRAFT; 


/* Print the sereen */ 
¢ (pave type I= PB_DAISY) 
‘Bospb.blkpte = Physbosech; 


witch (pb.pb_ercres = Getrex(>) © 
ease Ot po.phwidth = 320; 
‘po.pb_helght = 200; 
‘break: 


case 1: pbapb_width = 320; 


pb.po_height = 400; 
break; 


ele 
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pb.pb width 
pb.pb_hetaht 
break; 


pb-pb_colpal = dpalettetO); 


Pokew(OX4EEL, 19: 17 Set prtent, Locks out Serdmpt) */ 
if (Prebikcdpb) & 
CeonsetScreen print faited-\r\n"); 
> else 
{Cconusc"cannot print graphics on deisy wheel printer. \r\n"); 


[7 Print a text string */ 
pb.pb_blkptr = "\r\nThis {s 2 string.\r\w'; 
pb. po_width = steLentpb.pb blkptr); 
pb.pb-height = 0; 

Pokew(OsseEL, 1); 
If (Prtbikcepe) I= 0) 
CeonwstText print failed.\r\n"; 
return 0} 
> 


See Also 
TOS, xblos, xbios.h 


Pterm—gemdos function 76 (osbind.h) 
Terminate a process 
include <osbind.h> 
void Pterm( status) Int status; 


Pierm terminates the current process, and returns control to the parent process. 
status can bea status code that can be interpreted by the parent process, Pterm 
returns non-zero in the unlikely event that the process could not be terminated, 
Example 

This program exits with a non-zero status, 


Hinelude <oxbid.h> 


main € 
Prerm2); (/* Exit with return code set to 2 */ 

> 

See Also 

gemdos, Pexec, Pterm, Ptermres, TOS 
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Pterm0—gemdos function 0 (osbind.h) 
‘Terminate an TOS process 
#include <osbind.h> 
void Pterm0() 


PtermO0 terminates a TOS process, and never returns. 
Example 
For an example of this function, see the entry for Bconin, 


See Also 
gemdos, Pterm, Ptermres, TOS 


Ptermres—gemdos function 49 (osbind.h) 
Terminate a process but keep it in memory 
winclude <osbind.h> 
void Ptermres(x, code) long 7 int code; 


Ptermres terminates a process in TOS, but retains n bytes of the process it 
memory. code is the exit code for the process being terminated; it is returned t 
the process that invoked the current process. 


Example 
For an example of this function, see the entry for \auto. 


See Also 
gemdos, Pexee, Pterm, Pterm0, TOS 
Notes 


Programs that use this macro may not be portable to future ve 
but they are interesting to work with in the meantime, 


pun—Definition 
Tn the context of C, @ pun occurs when a programmer uses one data form int 
changeably with another. These puns are supported by the language's willing- 
ness (o apply implicit conversion rules. 


A pun most often occurs unintentionally when the programmer fails to dec! 
a function as returning a pointer, by default, what the function returns is 
sumed to be an int, thus creating a pun between the int and pointer into whi 
the function's return value is stored. No trouble will arise if the program is 
on a machine that defines an int and a pointer to be the same length; howe 
such code cannot be transported to an environment in which this is not the 
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See Also 
pointer, portability 


puntaes—xbios function 39 (osbind.h) 
Disable AES 
include <osbind.h.h> 
include <xbios.h> 
void Puntaes() 


Puntaes disables the AES. Note that this function may not work if the AES is 
in ROM. 


See Also 
TOS, xbios 


pute-STDIO macro (libe.a/pute) 
Write character to stream 
include <stdio.h> 
int pute(c, fp) char c; FILE */p; 


pute is a macro that writes a character conto file stream fp, and returns that 
character upon success, 


Example 
The following example demonstrates pute. 


Hinetude <atdionte 

inaing)¢ 
FILE *f 
int eh 
nt #oname (201; 
prineécventer file names"); 
sete filename); 


if (cfp = fopent fitenane, 
while ((ch = fgetc¢tp)) | 
puteteh, stdout); 
? 
else 
printf(Hcannot open 2s.\n", filename); 
felosettp): 
5 


See Also 
fpute, putchar, STDIO. 
The C Programming Language, pages 152, 166 
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Diagnostics 

EOF is returned when a write error occurs, 

Notes 

Because pute is a macro, arguments with side effects may not work as expected, 


putchar—STDIO macro (stdio.h) 
Write a character to standard output 
#include <stdio.h> 
int putchar(c) char c; 
putchar is a macro that expands to pute(c, stdout); it writes a character onto the 
standard output, 


Example 


Winctude <stdio.h> 
maingne 


Ant #idename 20); 
printtcventer file names"); 
etsCfilenane); 
AF CCfp = fopenctitenane, "899 I= MULL & 
nile CCch = fgetetfp)) I EOF) 
putehar eh; 
> 
tse 
peintf(*cannet open Xe.\n#, fi Lenane) 
feloset tp); 
By 
See Also 
{pute, pute, STDIO 
The C Programming Language, pages 144, 152 


Diagnostics 
EOF is returned when a write error occurs. 


Notes 
‘Because putchar is a macro, arguments with side effects may not work as ex- 
pected. 


puts—STDIO function (libe.2/puts) 
Write string to standard output 
#include <stdio.h> 
puts(string) char *siring 
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puts appends a newline character to the argument siring and writes the result on 
the standard output. 


See Also 
Tputs, STDIO 


putw—STDIO macro (stdio-h) 


pwd 


Write word to stream 
#include <stdio.h> 
putw(word, /p) int word; FILE */p; 


The macro putw writes word (an int) to the stream fp, and returns the value 
written. 


See Also 
Terror, STDIO 


Diagnostics 
putw returns EOF when an error occurs. A call to ferror may be needed to dis- 
Linguish this value from a valid data item, 


Notes 


Because putw is a macto, arguments with side effects may not work as expected. 
The bytes of word are written in the natural byte order of the machine. 


‘Command 

Print the name of the current directory 
pwd 
pwd p 
See Also 

cd, commands, msh 


ts the name of the current working directory, 
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‘sort—General function (Iibe.a/qsort) 
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Sort arrays in memory 
asort(data, n, size, comp) char *data; int n, size; int (*comp)(); 


qsort is a generalized algorithm for sorting arrays of data in primary memory. 
It uses C. A. R, Hoare's “quicksort algorithm. gsort works with a sequential 
array of memory called data, which is divided into n parts of size bytes each. 
In practice, data is usually an array of pointers or structures, and size is the 
sizeof the pointer or structure. Each routine compares pairs of items and ex- 
changes them as required. ‘The user-supplied routine to which comp points per- 
forms the comparison. 1t is called repeatedly, as follows: 

(eomp (pt, p29 

char "pt, *p2; 
Here, p/ and p2 each point to a block of size bytes in the data array. In prac- 
tice, they are usually pointers to pointers or pointers to structures, The com- 
parison routine must return a negative, zero, or positive result depending on 
whether p/ is logically less than, equal to, or greater than p2, respectively, 
Example 
For an example of how to use this function, see the entry for 


See Also 
shellsort, stremp, strnemp 
The Art of Computer Programming, vol. 3 


Notes 
sort uses a recursive algorithm that may overflow the default stack allocated; 
however, this is unlikely, 


alloc. 
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rand—General Function (libe.a/rand) 
Generate pseudo-random numbers 
int rand() 


rand generates linear, congruential, pseudo-random numbers, It returns in- 
tegers in the range 0 to 215-1, and purportedly has a period of 2°32, 


Example 
‘This example tests the functions rand and srand. It uses a threshold level that is 
passed in argy{1] (default, MAXVAL/2), the number of trials passed in argvi2] 
(default, 1,000), and a seed passed in argy{3] (default, no seeding), 
set ine MAKVAL 32767 /* range of rand(): 0, 2°51) */ 
ipaincarge, argv) int argc; char *arevtl; ¢ 

register Int {, hits, threshold, ntrials; 


sravEN} > RAKVALY2; 
trials = (erge > 2) ? atol argvi2i) + 1000; 
if (arge > 3) 
‘srandcatof (argv(3})9; 
for (1 = 1; 1 <x nteiats: §64) 
Sf (rand) > threshold) 
sehita: 


printf(vid values above Xd in Xd trials CDX).\nt, 
hits, threshold, ntriate, (1O0L*hits)/ntrial 


y 
See Also 

srand 

The Art of Computer Programming, vol. 2 


Random—xbios function 17 (osbind.h) 
Generate a 24-bit pseudo-random number 
include <osbind.h> 
#include <xbios.h> 
long Random() 


Random generates and returns a 24-bit pseudo-random number. The generator 
is seeded from the frame-counter, and is likely to be different every time the 
computer is turned on. 


Example 
The following example generates an array of random numbers. You may wish 
to use this as input for the example in mailoc, which demonstrates sorting. 
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Finclude <osbind.h> 
maint) € 


2031-9 € 
princfemsid ", Randan)); 
if ¢ ith a0) 

printf "WW" 9; 
> 
> 


See Also 

TOS, xbios 

The Art of Computer Programming, vol. 2 

Notes 

‘The lowest bit has a distribution of exactly 50%. 


random access—Definition 
In the context of computing, random access means that an entity, such as. 
memory, can be accessed at any point, not just at the beginning, This means 
that all points within memory can be accessed equally quickly. This contrasts. 
with sequential access, in which entities must be accessed in a particular order, 
40 that some entities take longer to access than do others. 


A tape drive is an example of s sequential access device, i.e., the order in which 
they stream past the tape head. Random-access memory (RAM) demonstrates. 
random access, Hard disks and floppy disks are combine elements of random 
‘access and sequential access. 


RAM, which usually consists of semiconductor integrated circuit 

strictly random access. In this regard, the term “RAM” is slightly misleading, 
and should be called “RWM", for read/write memory, contrasting it with read- 
only memory (ROM), which is also random access memory. 

See Also 
read-only memory 


ranlib—Definition 
The ranlib is a “directory” that appears at the beginning of each library. It 
contains the name of each global symbol (ie., function name) that appears 
within the library, and a pointer to the module in which that symbol is defined. 
‘Thus, the ranlib eliminates the need for the linker to search the entire library. 
sequentially to find a given global symbol, which speeds up linking noticeably. 


If the date on the library file is later than that in the ranlib header, the linker 


will ignore the ranlib and perform a sequential search through the library; the 
linker will also send the warning message 


rational number-rc_copy 


dutdated rantib 


to the standard error device, This is done to prevent the accidental use of an 
outdated ranlib, which could be disastrous. When you use the archiver ar to 
update a library or to create a new library, be sure to employ the options that 
update the rantib as well as modify or create the librar 


See Also 
ar, date, Id, touch 


Notes 

Under certain circumstances, it was possible to generate the Outdated ranlib er- 
ror message even though the ranlib was in fact up to date, In previous releases 
of Mark Williams C, this occurred when it was installed on a system with the 
date set to the current date, rather than not set, as requested in the installation 
procedures. Installing Mark Williams C with the date set on the system had the 
effect of updating the date stamp on the library files, which put the date on the 
ranlib header and that of its library file out of synch. The linker thus thought 
that the ranlib was outdated, when it was in fact correct. This problem was 
fixed on a previous release. 


rational number—Definition 
A ratlonal number is the quotient of two integers 


See Also 
integer, real number 


re_copy—AES function (libaes.a/re_copy) 

Copy a rectangle 

include <aesbind.h> 

int re_copy(oldrect, newrect) Rect *oldrect, *newrect; 


¥e_copy isan AES routine that copies a rectangle from one part of the screen to 
another. oldrect and newrect point, respectively, to the rectangle being copied 
and the area to which it is being copied, Each is defined as pointing to a struc- 
ture of the type Rect, which is defined in the header file aesbind.h, as follows: 

x X coordinate of rectangle 

y  ¥ coordinate of rectangle 

w width of rectangle 

h height of rectangle 


Fe_copy returns zero if an error occurred, and a number greater than zero if 
one did not. 
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See Also 
AES, TOS 
Notes 


A clipping rectangle should be set using the VDI function vs_clip before this 
routine is used. 


re_equal—AES function (libaes.a/re_equal) 


‘Compare two rectangles 
#include <aesbind.h> 
int re_equal(rect!, rect2) Rect *rect], *rect2; 
‘re_equal is an AES routine that compares two rectangles. rect/ and rect2 point 
to the two rectangles being compared. Each is declared as pointing to a struc- 
ture of the type Rect, which is defined in the header file aesbind.h, as follows: 
x X coordinate of rectangle 
y  Y coordinate of rectangle 
w width of rectangle 
h height of rectangle 


re_equal returns zero if the rectangles are not identical, and one if they are, 


See Also 
AES, TOS 


r¢_intersect—AES function (libaes.a/re_intersect) 
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Check if two rectangles intersect 
#include <aesbind,h> 
int re_interseet(rect!, reci2) Reet *rect1. *rect2s 


re_intersect is an AES routine that check to see if two rectangles intersect, 
rect! and rect2 point to the two tectangles being compared. Each is dectared as 
pointing to a structure of the type Rect, which is defined in the header file aes~ 
bind.h, as follows: 


x X coordinate of rectangle 
y  Y coordinate of rectangle 
w width of rectangle 
hh height of rectangle 


The values of the structure to which reet2 points will be changed to the coor- 
dinates of the area common to both rectangles, or to nonsense if they do not in— 
tersect. re_intersect returns zero if the rectangles do not intersect, and one if 
they do. 
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See Also 
AES, TOS 


AS function (libaes.a/te_union) 
Calculate overlap between two rectangles 
#include <aesbind.h> 

void re_union(rect!, rect2) Rect *rect!., *reci2; 


re_uni 


re_union ig an AES routine that computes a rectangle that encloses two over- 
lapping rectangles. rect! and reet2 point to the two overlapping rectangles. 
Each is declared as pointing to a structure of the type Rect, which is defined in 
the header file aesbind-h, as follows: 


x X coordinate of rectangle 
y  ¥ coordinate of rectangle 
width of rectangle 
height of rectangle 


me 


The values of the structure to which rect2 points will be changed to the coo: 
Ginates of the rectangle that encloses the overlapping rectangles; these variables 
are set to nonsense if the rectangles do not intersect, re_union returns nothing 


See Also 

AES, TOS 

Notes 

This routine should be used only if you are certain that the rectangles in ques- 
tion do overlap. The routine re_intersect returns a value that indicates iI the 
rectangles do in fact overlap. 


read UNIX system call (Jibe.a/read) 
Read froma file 
read(fd, buffer, n) int fd: char *huffer; iat 1; 


read reads up to m bytes of data from the file descriptor fa and places them into 
the data segment at address buffer, The amount of data actually read may be 
less than that requested if EOF is encoumered, The data are read at the current 
seek position in the file, which was set by the most recently executed read or 
Iseek routine. read advances the seek pointer by the numer of characters actu- 
ally read. 


Example 
For an example of how to we this function, see the entry for open 
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read-only memory—Definition 


real numbers-—Definition 


realloc—General function (Iibe.a/realloc) 
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See Also 

UNIX routines, STDIO 

Diagnostics 

With a successful call, read returns the number of bytes read; thus, zero byt 
signals the end of the file. It returns -I if an error accurs: bad file descripto 
bad hu/fer address, and physical read error are among the possibilities. 

Notes 

read is a low-level call that passes data directly to TOS. It should not be inter- 
mixed with high-level calls, such as fread, fwrite, or fopen, without caution, 


As its name suggests, read-only memory, or ROM, is memory that can be re 
but not written to, It most often is used to store material that is used frequently! 
or in key situations, such as a language interpreter ora boot routine, 
See Also 

random access 


A real number is any number of the set of rational numbers or irrational num 
bers 

Sev Also 

float, rational number, integer, irrational aumber 


Reallocate dynamic memory 
char *realloc(pir, size) char "ptr; unsigned size; 


realloc helps to manage a program's arena, It returns a block of size bytes that 
holds the contents of the old block, up to the smaller of the old and new size 
realloc tries to return the same block, truncated or extended; if size is small 
than the size of the old block, realloc will return the same pir, 


See Also 
arena, calloc, free, Icalloe, Imalloc, Irealloc, malloc, notmem, setbuf 


Diagnostics 

realloc returns NULL if insufficient memory is available. It prints a messa} 
and calls abort if it discovers that the arena has been corrupted, which most of 
ten occurs by storing past the bounds of an allocated block. realloc will behave 
unpredictably if handed an incorrect pir. 


‘The related function Irealloc takes an unsigned long as its size argument, 
therefore can reallocate memory blocks that are larger than 64 Kilobytes, 
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record-Definition 
‘A record is set of data of a fixed length that has been given a unique iden- 
tifier, and whose structure conforms to an exact description. An example of a 
record is an entry in an entry in a file of names and addresses: each entry has. 
fixed length, is marked by a unique identifier, and has 1 fixed number of bytes 
set aside in fixed order to record name, address, city, state, and ZIP code. 


Note, t00, that what is called a “record” in Pascal is called a “structure” in C. 


See Also 
field, structure 


Rect- Definition 
Rect is a structure that is defined in the header file aesbind.h. It defines a rec~ 
tangle in a manner that can be understood by an AES routine. It consists of 
four integers, as follows: 


x X coordinate of rectangle 

y  Y coordinate of rectangle 

w width of rectangle 

hh height of rectangle 
Because Mark Williams C allows you to pass a structure directly, this structure 
can be placed in the argument list of AES functions to replace the four ar 
guments that indicate coordinates, height, and width of a rectangle, 
See Also 
AES, aesbind.t 


|, struct, TOS 


registe—Definition 
'A register is memory within a microprocessor within which data can be stored 
and modified. The size and the configuration of a microprocessor’s registers 
affect its computing potential, Registers can be manipulated much faster than 
RAM. 


See Also 
register variable 


(or Yariable—Definition 

register is a C storage class. A register declaration tells the compiler to try to 
keep the defined local data item in a machine register. Under Mark Williams C, 
the int foo can be declared to be a register variable with the following 
statement, 
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register int foo: 

Qn the 18086, two registers are available to accept register variables; if m 
than two are declared, all after the first two will be treated as ordinary aut 
‘On the 68000, eight registers are available to accept register variables: three ad~ 
dress registers and five data registers. 


By definition of the C language, registers have no addresses, so pointers 
registers cannot be passed as function arguments. Placing heavily-used | 
variables into registers often improves performance, but in some cases declay 
register variables can degrade performance somew! 
See Also 

au(o, extern, static, storage class 

The C Programming Language, page 81 


rewind—STDIO function (libe.a/rewind) 


Findex—String function (libe. 


Reset file pointer 

#include <stdio.h> 

rewind(/p) FILE */p; 

rewind resets the file pointer to the beginning of stream /p; it is a synonym for: 
fseek(/p, OL, 0). 


See Also 
feck, STDIO 


Find a character in a string 
char *rindex( string, c) char *siring; char ¢ 


rindex scans siring for the last occurrence of character c, If ¢ is found, rind 
returns a pointer fo it, If it is not found, rindex returns NULL. 4 
Example 
‘This example, when handed a path name, returns a pointer to a file name with: 
the leading directory information stripped away. 
det ine PATHSED "\\" /* path nane separator */ 
extern char "rides 
bsenane(path) register char *peth; 
« 

register cher tep: 

return (ep = rindex(path, PATHSEPD) == MULL) 7 path 2 +p); 
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Sve Also 
index, string 


Command 
Remove files 
rm file. 


rm removes each file, and frees data blocks assoc’ 


See Also. 
commands, msh, rmdir 


rmdie-Command 
Remove a directory 
rmdir directory ... 


tmdir removes each directory. This will not be allowed if a directory is the cur- 
rent working directory or is not empty, 


rmdir will not allow you to remove the current working directory 


See Also 
commands, mkdir, msh, rm 


rsconf—Command 
Reconfigure the serial port 
rsconf speed. flow, UCR, RSR. TSR. SCR 


rsconf is @ command that uses the xbios function Rsconf to reconfigure the 


serial port, speed is the baud rate to which the port will be set; /low sets the 
form of flow control. UCR is a bit map that sets the control register; RSR is 
bit map that sets the receive status; J'SR is a bit map that sets the transmission 


status; and SCR sets the synchronous character register, For details on the 
values for these arguments, see the entry for Rsconf. 


See Also 
commands, Rsconf, TOS 


Rsconf—xbios function 15 (osbind.h) 
Configure the serial port 
#include <osbind.h> 
include <xblos.h> 
yoid Reconf(specd, flow. UCR, RSR.TSR. SCR) 
int speed, flow, UCR. RSR, TSR. SCR: 
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Rsconf 


Reconf configures the serial port, and returns nothing. speed is an integer that 
sets the baud, as follows: 


0 19,200 8 600 
1 9600 9 300 
2 4800 10 200 
3 3600 Wn 150 
4 2400 12 134 
5 2000 13 110 
6 1800 14 
7 1200 15 30 


‘flow is an integer that sets the flow control, as follows: 


0 None (the default) 

1 XON/XOFF (<ctrl-S>/<ctrl-Q>) 

2 Request to send/clear to send (RTS/CTS) 
3. XON/XOFF and RTS/CTS 


UCR stands for USART control register. (USART, in tura, means universal 
syachronous-asynchronous receiver-transmitter). This variable is an byte- 
length bit map that controls the operation of the serial port. Its bits encode the 
Following information: 


Bit 0 unused 
Bit1 0 indicates odd parity; 1, even parity 
Bit 2 0 indicates no parity; 1, parity as set in bit 1 
Bits 3,4 Start/stop bits and format: 

00 synchronous; start 

10 asynchronous; start- 

01 asynchronous; startel; stop=1,5 

11 asynchronous; start=1; stop: 
Bits 5,6 Word length: 

00 

10 

OL 

nL 
Bit7 0=Use frequency from transmit control 


and receive control directly 
L=Divide frequency by 16 


RSR isa byte-length bit map that controls the receive status register; setting the 
bits sets the following conditions; 
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Enable reception 

An synchronous mode, enable comparison of 
character in SCR with character in 

receive buffer 

In synchronous mode, signal that charscter 
identical to character in SCR may be 
received; in asynchronous mode, 

signal reception of start bit 

In synchronous mode, signal that character 
identical to character in SCR has been 
received; in asynchronous made, 

signal reception of BREAK 

Signal frame error: stop bit isa NUL, but 
byte received is not 


Bit4 


Bits Signal parity error 
Bit 6 Signal buffer overrun, 
Bit7 Signal buffer full 


TSR isa byte-length bit map that controls the transmitter status register. T! 
bits in this map indicate the following: 


Enable transmission 
High or low output mode: 


00 High 
10 High 
ol Low 
11 Loop-back mode 

Bit3 In synchronous mode, not used; in 
asynchronous, sends break condition 

Bit4 Send end-of-transmission character after 
current character 

Bits Switch to reception immediately after 
end of transmission 

Bits Send character in sender flosting register 
before writing new character into send 
buffer 

Bit7 Buffer empty 


Finally, SCR initializes the synchronous character register, this variable should 
be set to zero. 


Note that setting UCR, RSR, TSR, or SCR to =1 will cause it to be ignored by 
TOS. 
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rsre_free—AES function (libaes.a/rsrc_free) 


rsr¢_gaddr—AES function (libaes.a/rsre_gaddr) 
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Example 
This example sets the serial port to 4800 baud with XON/XOFF flow control 
For an example of using this function from the \auto directory, see the en! 
for \auto. 


include <osbind.h> 


‘define Be 4800 (2) 7+ $800 baud */ 
‘define FC_XON C1) 77 YOMNOFF */ 
maine? © 


Reconf(@R 4800, FCXON, “1, <1, -1, -135 
Ceonws("Serial ‘port set to’ 4800 baud, SON/XOFF\M\); 
+ 


See Also 
TOS, xbios 


Notes 

Resetting the speed, even if there is no change, will transmit an ASCII DI 
across the serial line. This may be intended to help remote systems or moder 
to dotormino line speed. 


Free memory allocated to a set of resources 
#include <aesbind.h> 
int rsre_free() 


rste_free is an AES routine that frees the random-sccess memory that had 
allogated to a set of resources by the routine rsre_load. Becsuse the contents of 
only one resource file can be kept in memory af any given time, this routi 
should be employed before loading a second resource file. rsre’ load rat 

zero if an error occurred, and a number greater than zero if one did not. 


See Also 
AES, TOS 


Get the address of a resource object 
#include <aesbind.h> 
int rsre_gaddr(eype, index, address) int type, index; char *address; 


rste_gaddr is an AES routine that gets the address of a given resource obj 
ype Indicates the type of object being sought, as follows: 
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object tree 
object within a tree 

text (TEDINFO) 

icon (ICONBLK) 

predefined bit pattern (BITBLK) 

string 

image data 

object specification 

pointer to text (TEDINFO) 

pointer to text template (TEDINFO) 
pointer to text validation string (TEDINFO) 
pointer to mask for icon image (ICONBLK) 
pointer to data for icon image (ICONBLK) 
pointer to icon text (ICONBLK) 

pointer to bit image (BITBLK) 

address of pointer to free string 

16 address of pointer to free image 


iedex gives the index number of the object within the object tree. address 
points to the address of the data sought; this value is set by the routine. 
rsrc_gaddr returns zero if an error occurred, and a number greater than zero if 
one did not, 


See Also 
AES, TOS 


tste_load—AES function (libaes.a/rsre_load) 
Lnad a resource file into memory 
#include <aesbind.h> 
int rsre_load( filename) char */ilenamé; 


rsre_load is an AES routine that tosds a resource file into memory. filename 
points to the name of the file to be loaded. Note that by convention, the name 
of the file must have the suffix .rse, 

Note that only one resource file ean be loaded into memory at any given time: 
rsre_load automatically calls rsre_free to free the memory allocated to any 
previously loaded resource file, rsre_load returns zero if an error occurred, 
and a number greater than zero if one did not. 

See Also 

AES, TOS 
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rsre_obfix—AES function (libaes.a/rsre_obfix) 


rste_saddr—AES function (libaes.a/rsre_s 


Change the form of an object's coordinates 
#include <aesbind.h> 

+#include <obdefs.h> 

int rsre_obfix(Jree, ohject) char *tree; int objects 


rsrc_obfix is an AES routine that changes the form the coordinates for an ob- 
Ject that is stored in a resource file, A resource file encodes an object's coor- 
dinates in the form of character coordinates, not pixel coordinates; these 
character coordinates are transformed into pixel coordinates when the resource 
file is loaded, when the resolution of the screen is known. tree points to the ad~ 
dress of the tree that contains the object in question, and object is the number 
of the object within the tree, rsre_obfix always returns one, 


See Also 
AES, TOS 


ddr) 
Store address of a free string or a bit image 

#include <aesbind.h> 

int rsre_saddr(sype. index, address) int type, index; char "address; 


rsre_saddr is an AES routine that copies into an object the address of a pointer 
to either the free string or the free image of another object within the object 
tree. ype denotes the type of pointer whose address is being stored: 15 in- 
dicates a pointer to a free string, and 16 indicates a pointer to a bit image. 
rsee_saddr returns zero if an error occurred, and a number greater than zero if 
one did not. 


See Also 
AES, TOS 


runtime startup—Definition 


402 


‘The C runtime startup is an initialization routine that is linked with a C 
program as the first part of an executable object program. It performs the 
Functions necessary to start and terminate the C environment. Ata minimum, 


it initializes the stack, calls main, and calls exit with the return value from 


Three C runtime startup routines are available on Mark Williams C for the Atari 
ST; erts0.0, the normal runtime startup; crtsg.o, the runtime startup for the 
GEM environment; and ertsd.o, which is used to create a GEM desktop ap- 
plication. The default is erts0.0, which is appropriate for most uses. You can 
call crtsg.o on the ce command line in either of two ways: with the switch 
-VGEM, or with the name option Nrertsg.o. The ertsd.o start-up routine can 
be called with the option -VGEMACC or with the name option Nertsd.o. 
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See Also 
cc, erts0.0, ertsd.o, ertsg.o, stack, _stksize 


rvalue—Definition 
‘An rvalue is the value of an expression. The name comes from the assignment 
expression el=e2;, in which the right operand is an rvalue. 


See Also 
Twalue 


‘Rywabs—bios function 4 (osbind-h) 

Read or write data on a disk drive 
iclude <osbind.h> 

include <bios.h> 

long Rwabs(rorw, buffer, n, rec, drive) 
int rorw, n, rec, drive; char *buffer; 


Rwabs reads from or writes data to a disk drive. rory indicates whether the 
process will read or write; zero indicates read, and one indicates write. n is the 
number of sectors to transfer; rec is the number of the first record to transfer; 
and drive is the name of the disk drive to use: zero indicates drive A, one in- 
dicates drive B, etc. buffer points to the area to which the data are to be writ- 
ten, or from which they are to be read. 


See Also 
bios, TOS 
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scanf—STDIO function (libe.a/scanf) 
Format input 
+#include <stdio.h> 
seanf(format [, arg ]...) char *format; 
seanf reads the standard input, and uses the string format to specify a format 
for each arg, each of which must be a pointer. seanf reads one character at a 
time from format; white space characters are ignored. The percent sign charac- 
ter ‘Ob’ marks the beginning of a conversion specification. “%4' may be followed 
by characters that indicate the width of the input field and the type of conver— 
sion to be done. The following modifiers, in this order, may precede the con= 
version type: 


1. The asterisk “*", which indicates that the next input field should be 
skipped rather than assigned to the next arg. 


A string of decimal digits, which specifies a maximum Field width. 


An I, which specifies that the next input item isa long object rather than 
an int object, Capitalizing the conversion character has the same effect. 


The following conversion characters are recognized: 


¢ Assign the next input character to the next arg, which should be of type” 
char *, 


d Assign the decimal integer from the next input field to the next arg, 
which should be of type int *, 


D Assign the decimal integer from the next input field to the next arg, 
which should be of type long *. 


© Assign the floating point number from the next input field to the next” 
arg, which should be of type float *. 


E Assign the floating point number from the next input field to the next 
arg, which should be of type double *, 


f Same ase. 
F Same as E, 


© Assign the octal integer from the next input field to the next arg, which 
should be of type int *, 

© Assign the octal integer from the next input field to the next arg, which) 
should be of type long *, 


s _ Assign the string from the next input field to the next arg, which shoul 
be of type char *. The array to which the char ** points should be long 
enough to accept the string and a terminating NUL character. 
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x Assign the hexadecimal Integer from the next Input field to the next arg, 
which should be of type int *, 


Assign the hexadecimal integer from the next input field to the next arg, 
which should be of type long 


See Also 
STDIO 
The C Programming Language, page 147 


Notes 

Because C does not perform type checking, it is essential that an argument 
match its specification; for that reason, scant is best used to process only data 
that you are certain is in the correct data format, The use of upper-case format 
characters to specify fong arguments is not standard; use the ‘I’ modifier for 
portability. 


-rdmp—xbios function 20 (osbind.h) 
Print a dump of the screen 

#include <osbind.h> 

+#include <xbios.h> 

yoid Serdmp() 


Serdmp dumps the screen to the printer port, and returns nothing, Note that at 
present this routine works only with the monochrome monitor, 


Example 

This example dumps the screen to a printer. Be sure that before you use this 
example, your printer is plugged into your computer, properly described to 
TOS, and turned on, 


finetinte <oobire. te 
Hnclude <bios.h> 


rained € 
Sf CGeostat(oe PRT) == 0) 
‘ceonwst "The printer Ts not ready.\n\n" 93 


else 
Cconvs( *The screen is being printed... Please waie-\n\r" 37 
seraipe) 
Ceonus¢ "The sereen is printed.\n\r 9; 


> 


Feturncor; 


See Also 
TOS, xbios 
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‘The Atari ST uses the following escape sequences to control the terminal screen, 
‘These can be passed by the macro Cconout, as well as by numerous other output 
routines, to manipulate the Atari ST's screen: 


Note that <ese> represents the escape character, ASCIT 033. 


<ese>A Cursor up 

<esc>B Cursor down 

<ese>C Cursor forward 

<ese>D Cursor backward 

<esc>E Clear screen, home cursor 

<esc>H Home cursor 

<ese>T Return {0 same position on previous fine 

<esc>J Erase to the end of the page 

<esc>K Clear to the end of the line 

<ese>L Insert line 

<esc>M Delete line 

<ese>Y row col 
Position cursor at row, col, which are 
row/column numbers plus 040 (space character) 

<ese>be Set foreground color to.c 

<esc>co Set background color toc 

<esc>d Erase beginning of display 


<ese>e Make cursor visible 
<ese>f Make cursor invisible 

<ese>j Save cursor position 

<esc>k Restore cursor position 

<ese>i Erase a line 

<ese>o Erase from beginning of line to cursor 
<esc>p Enter reverse video mode 

<ese>q Exit reverse video mode 

<esc>y Wrap text at end of line 


<esc>w Discard text at end of line 


For the sequences <esc>b and <esc>e, the variable c is the color index plus 040. 
In monochrome mode, the color index can be zero or ane; in medium resolu= 
tion, it can be zero through three; and in low resolution, it can be one through: 
15. 


Example 
The following example clears the screen and homes the cursor, then moves th 
cursor fo row 12, column 6 on the screen, 
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wating) 
char row 
char colunn = 6+'\040'; 


+1060"; 


printfC\O33E"); 
printfONO3BVHc%e™, row, column); 

) 

see Also. 

Ceonout, gemdos, TOS 


serp_read—AES Function (libaes.a/serp_read) 
—Read the scrap directory 

include <aesbind, h> 

int serp_read(buffer) char “buffer; 


The “scrap” feature provides a way for applications to pass information among 
themselves. 


‘The information to be passed is written into a file, which is always called 
scrap.xxx. The suffix indicates what type of information the file contains: text 
(txt), 2 GEM metafile (,gem), a bit image (.img), or spreadsheet data (.dif). 


‘The name of the directory that holds the scrap file is writien into a static buif- 
ex, or clipboard. The clipboard contains only the name of the directory in which 
‘the information is kept, not the information itself. The clipboard is overwritten 
cach time it is used, so in effect only one scrap file can be used at any given, 
time, AES provides routines for reading and writing to the clipboard; it is up to 
you to see to it that the scrap file is correctly written and read. 


serp_read is an AES routine that reads the clipboard. buffer points to the name 
of a buffer into which the contents of the clipboard will be written. scrp_read 
returns zero if an error occurred, and a number greater then zero if one did not. 


See Also 
AES, TOS 


serp_yirite—AES function (libaes.a/serp_write) 
Write to the scrap directory 
#include <aesbind.b> 
int serp_write(directory) char “directory; 


scrp_write is an AES routine that writes the name of the scrap dircctory onto 
the clipboard. directory is the name of the scrap directory. serp_write returns 
zero if an error occurred, and 2 number greater than zero if one did not. For 
more information on using the clipboard, see the entry for serp_read. 
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setbuf—STDIO function (libe.a/setbuf) 
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Set an msh variable 
set [VARIABLE=value] 


set sets sets the msh VARIABLE to value. For example, the command 
‘set be"br\bin™ 

tells msh that the variable b is equivalent to b:\bin; thus, typing 
ed Sb 

is equivalent to typing 
ca br\pin 


Typing set without an argument displays all the variebles that have been set, 
Typing 


set in history 
lists the contents of the shell’s history buffer. Typing 
set in Bin: 


lists the installed built-in functions; .bim is msh's internal directory, which 
points to areas in absolute memory where commands are stored. 


Additional forms of the built-in functions can be installed into .bin with the sef 
command, For example, the command 


‘set in bin offeteursconf 3" 

installs the command off into .bin, and declares it to be equivalent to the com- 
mand cursconf 3, cursconf is a command that is built into the micro-shell, and 
uses the TOS function Cursconf to manipulate the system cursor. This com= 
mand turns off the cursor blink. 


See Also 
‘commands, msh, unset 


Set alternative stream buffers 
#include <stdio.h> 
setbuf(/p, buffer) FILE *fp; char *tuffer; 


‘The standard 1/0 library STDIO automatically buffers all data read and writt 
in streams, with the exception of streams to terminal devices, STDIO normal 
uses malloc to allocate the buffer, which is a char array BUFSIZ charact 


Mark Williams C 


yexicon setcol-Setcolor 


jong; BUFSIZ, is defined in the header file stdio.h, setbuf’s arguments are the 
stream pointer fp and a buffer to be associated with the stream. The call should 
be issued after the stream has been opened, but before any input or output re- 
quest has been issued, The buffer passed to sethuf may be NULL, in which case 
the stream will be unbuffered, or must contain at least BUFSIZ bytes. 


See Also 
STDIO 


seteol Command 
Reset a color 
seteal color, value 


setcol is @ command that uses the xbios function Setcolor to reset a color. color 
is the entry in the color palette that you wish to reset, from zero through 15. 
value is a three-digit octal number that indicates the color to which you wish to 
set color. 


See Also 
commands, getcol, TOS 


Setcolor—xbios function 7 (osbind.h) 
Set one color 
;clude <osbind.h> 
include <xbios.h> 
int Seteolor(number, value) int number, values 


Seicolor sets one color. number is the element on the color palette that is being 
redefined; it can be any number from zero to 15. value is the color value to 
which number is being reset; setting any number to a negative value ensures that 
no change is made. 


(On monochrome monitors, 
Setcotor(0, 0); 

gives a black background and white letters, whereas 
Seteotor(O, 1); 

switches the screen toa white background and black letters. 


Setcolor returns the old value of number. The change will be made during the 
next vertical blank, 

Examples 

The first example reads and prints out the values of the color map. For another 
example, see the entry for Seteolor. 
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include <oebind.b> 
colar dispcindx, vat) 


int red, green, blue; 


red = (vater8) & 7; [7 Red volue in bite 8:10 +/ 
areen = (val2>4) & 7; f Green value in bits 4-6 #/ 
Blue = val 2 7 Blue value in bits 0-2 */ 
printf( " i2d + 1d td BId\nt, indk, red, green, blue 

> 

maine ¢ 
int 13 
prin? "Entry RG B\N" 9; 
for ¢ i=0; i<16 ; 4+) 
color disp i, Setcolort 1, “195 

2 


The second example works with a monochromatic monitor. Tt reverses 
colors of the characters and background, 


#inetude <oabind.h> 
sing) 
int color = Seteoten(®, -13; 
Setcoler(d, ++colork2); 
> 
See Also 
TOS, xbios 


setenv—Command 
Set an environmental variable 
seteny [VARIABLE=value] 


sefeny sets an environmental variable, Environmental variables are those 
are exported, or handed to other programs for their use at run time. For 
ample, the environmental variable TIMEZONE is read by the C routine e 
as part of its time-handling work: whereas the environmental variab 
LIBPATH is read by the linker Id to locate its libraries. 


You are free to define new environmental variables within your programs, 


vironmental variable with capital letters. 


Typing seteny without any arguments displays all of the environmental varia 
that have been set so far. 
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See Also 
commands, msh, unseteny 


Setexe—bios function 5 (osbind-h) 
Get or set an exception vector 
#include <osbind.h> 
finclude <bios.h> 
Tong Setexc(number, address) int number; char *address; 


Setexe gets or sets an exception vector. Vectors 0x00 through OxFF are defined 
bby the 68000 hardware; the extended vectors are defined in the header file sig- 
nal.h, as Follows: 


Ox100 timer tick 

oxt01 critical error handler 

ox102 terminate handler 
0x103-Ox1FF reserved for future use by TOS 
0x200-0x2FF reserved for future use by users 


mumber is the number of the exception vector to be read or set. address is the 
address to be set into the exception table; -1 indicates that the vector is to be 
read rather than set. Setexc returns either the previous address if it is setting 
the vector, or the current address if is reading the vector. 
Example 
‘This example shows how to use Setexe to trap divide-by-rero errors. Note that 
this program calls the routine setrte, which is included with Mark Williams Cin 
the file setrte.s. To compile, use the command line 

ce -0 Setexc.prg Setexc.c setrte.s 
‘The Following gives the text of Setexe.e: 
finetude <oebind.t> 
define Divo (5) J* Divide by 0 vector number *) 
iverr() 

setrtet): /* Hake this en exception routine */ 

Ceanss¢\r\ vision by O\r\n): 
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sain € 
register unsigned long oldvec; 


oldvec = (unstened long)setexcto1V0, diverr); 
7 Set the excention */ 

printfcithis is @ test of divide by 0...\n! 

B= 133/a: 7 Generate error */ 

printf("The result of 133/%d is Ke\n", a, DD; 

Setexc(OIVO, oldvee! 7 Set vector back */ 

exit(O); 7 Return to system */ 


See Also 
bios, signal.h, TOS 


Notes 
TOS does not reset exception vectors on process termination; therefore, you 
‘must reset them yourself or face the consequences. 


set}mp—General function (libe.a/setimp) 
Perform non-local goto 
#include <set]mp.h> 
set}mp(env) jmp_buf env; 


The function call is the only mechanism that C provides to transfer control be~ 
tween functions. This mechanism is inadequate for some purposes, such as 
handling unexpected ertors or interrupts at lower levels of a program. To 
answer this need, setimp helps to provide a non-local goto facility. setimp saves 
a stack context in env, and returns velue zero. The stack context can be res- 
tored with the function longjmp, The type declaration for jmp_buf is in the 
header file setjmp.h. The context saved includes the program counter, stack. 
pointer, and stack frame. This routine does not restore register variables, but 
other variables are not affected. 

See Also 

getenv, longimp, setimp.h 

Notes 

Programmers should note that many user-level routines cannot be interrupted 
and reentered safely, For that reason, improper use of setjmp and longjmp will 
result in the creation of mysterious and irreproducible bugs. The use of 
longjmp to exit interrupt exception or signal handlers is particularly hazardous. 


setimp.h—Header file 
Header file for setimp and longjmp functions 
#include <setimp.h> 
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setjmp-h defines the structure jmp_buf for a setjmp environment. 


See Also 
header file, longjmp, setimp 


setpal—Command 
Reset the color palette 
setpal 
setpal is a command that uses the xbios function Setpallete (sic) to reset the sy 
tem's color palette, 


See Also 
commands, getpal, TOS 


‘Setpallete—xbios function 6 (osbind.h) 

Set the sereen’s color palette 

#include <osbind.h> 
include <xbios.h> 
void Setpallete(paleite) int palettel16; 
Setpallete (sic) sets the screen's color palette, and returns nothing. paleite 
points to an array of 16 hexadecimal integers, each of which indicates a dif- 
ferent color. The palette is implemented at the next vertical blank interval. 
Example 
This example sets the color palette, A palette is a table of 16 words containing 
the definitions for 16 colors as indexed by set bits in the “planes” 
include <osbind.h> 


short ugly) = ¢ 
(x000, Ox111, 03222, 0x333, 
Dxbéd, 02555, 03666, 9377, 
(x007, 0x070, 0x700, Ox707, 
(x770, Ox077, 0x737, 0x337 
2% 

rain © 
Setpalletat ugly 9; 

? 


See Also 
TOS, xbios 


setphys—Cammand 
Reset physical screen’s display space 
setphys address 
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setphys is a command that resets the physical screen’s display base. address is 
the address of the aew display base, 


See Also 
commands, getphys, TOS 


setprt—Command 
Reset the printer port 
setprt configuration 


setprt is a commend that uses the xbios function Setprt to reconfigure the 
printer port. configuration is an integer that indicates the port's new configura- 
tion. For a table of the configuration codes, see the entry for Setprt. 

See Also 

commands, Setprt, TOS. 


Setprt—xbios function 33 (osbind.h) 
Get or set the printer's configuration 
#include <osbind.k> 
#include <xblos.h> 
Int Setprt(con figuration) int configuration; 


Setprt gets or sets the configuration of the printer port. configuration is a 16- 
bit map that configures the port. If it is set to OxFFFF (-1), the port's current 
configuration is read; otherwise, its value is used to set the port, as follows: 


0x01 daisywheel printer 
0x02 monochrome printer 
0x04 if set, Epson-type dot-matrix printer; if not, Arari printer 
0x08 if set, final mode; if not, draft mode 
Ox10 if set, printer uses serial port; if not, printer port 
0x20 if set, uses single sheets; if not, uses Fanfold paper 
Bits 6 through 14 are reserved, and bit 15 must be zero. These values are 
defined in the header file xbios.h. 
Setprt returns the printer port's current configuration when configuration is set 
to -1; otherwise, it returns a meaningless value, 
Example 
For examples of this function, see the entries for \auto and prtblk. 
See Also 
Prtblk, TOS, xbios, xbios.h 
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setrex—Command 
Reset the screen resolution 
setrez resolution 


setrez is a command that resets the screen’s resolution. resolution indicates the 
new Screen resolution, as follows: zero, high resolution; one, medium resolution; 
and two, low resolution. Note that using this command inappropriately (0.8., 
resetting a monochromatic monitor to low resolution) will cause a meaningless 
jumble to appear on the screen, 


See Also 
commands, getrez, Getrez, TOS 


‘Setsereen—xbios function 5 (osbind.h) 
Set the video parameters 
include <osbind.b> 
include <xbios.h> 
yoid Setscreen(log, phys, res) char *log, *phys; int res; 


Setsereen sets the video parameters, and returns nothing. Jog and phys are the 
bases of the logical and physical screen displays. res is the new screen resolu- 
tion: 

0 high resolution 

1 medium resolution 

2 tow resolution 


Setting any variable to a negative number ensures that that variable will be ig- 
nored, 


ample 
‘This example demonstrates Setscreen, 


inelude <osbind.h> 
include <bios.h> 


maine) € 
char *newser, *oldser, *nenbtky 
int x, 5 


Ceonsstiorking. An; 
cldscr = (char #) Physbasec; 


if C(menbLk = (char *)MalLoe(32*1026L)) == 0) 
printf(talloc of Ald bytes failed.\n", 3210261); 
Prerm); 
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rewscr = (char #) ¢¢¢ong) menbtk + OXFFL) & =COxFFL)); 
Setscreen(newser,-1L,-197 /* Change Logicat base */ 
conws(*\O33H\E33I"; V# Clear Logical screen */ 


for (yO; ¥<2h; ye4) /* for 20 rows... */ 

for (x20; x39; xe) CJ 39 tines eache.. 4/ 
Beonaut(BC_RAW, OX0E); 
Beonout(BC_RAW, Ox0F); 


> 
‘Ceonws¢"\r\n"); 

5 

Setécreont=tL newser,-1)5 

ceonin(); 

Setscreenoldser,oldser,-1); J* Restore addresses... */ 

return 0; 


J* Hove physical base... */ 


7 


See Also 
Getrez, Logbase, Physbase, TOS, xbios 


Settime—xbios function 22 (osbind.h) 
Set the current time 
#include <osbind. b> 
#include <xbios.h> 
void Settime(datetime) long datetime; 


Settime sets the current time and date for the intelligent keyboard (IKBD), and 
returns nothing, datetime is a 32-bit mask whose bits indicate the following: 


0-4 no. of two-second increments (0-29) 
5-8 no. of minutes (0-59) 
9-15 no. of hours (0-23) 


16-20 day of the month (1-31) 
21-26 month (1-12) 
27-31 year (0-119, 0 indicates 1980) 
Example 


This examples sets the IKBD time. Note that this does not affect the current 
GEM-DOS time. 
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‘an Settime 


Winelude <osbind.h 


rained € 
register unsigned long tine: 
int seconds; 
int minutes; 
int hours; 
int day 
nt month; 
‘nt year 


print Center the dete and time cIOUDO/YYYY Hom): 
Scant (24/2 day, tyeer, Bhours, minutes 9; 
Seconds = 0; 
iftyear < 100) 
Year = 1900; 
tine = "Cunaiened loned (veer 19809<<259 
|(constenes Lera}manthee2T) 
[CCunstgned Longyday<<t6) 
|ccansigned Lonaphaurseett) 
|(Cunsigned Longyminutes<<5) 
IcCansigned Lona sceands>>i)z 
tineprin(We are setting the tine to", tine 3; 
settine tine); 


* verity what we oid. */ 


time = cettine(); 
tineprine (hat ve get is, timed; 


> 
void fixdiacbuf, onunber, size) 


char *huf; 
int enunber; 
« 


register Long Linit; 
register long nutber; 


umber = onunber 


Limit = 10; 
for (@ = 1} 0 < cize : of) 
Unie 
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if (Grunber >= Limit)| |(eurber <0)) € 
for (0 = 0; © < size; or) 
meus 

buf = 0; 

return; 


0; ©< sizer ot) € 
19; 

‘olerumbers Limit 

umber init; 


5 


Rineprint (string, tine) 
char *etring? 
register unsigned Leng tine; 


€ 
int seconds; 
‘int minutes; 
‘int hours; 
char minet303 
char secs; 
seconds = (tine & Ox001F) << 17 r 
iminutes = (tine >> 5). & Gx3F; fn 
houra = (sine >> 11) & Ox; ” 
day = (tine >> 16) & Oxi; # 
fonth = (eine >> 21) & OXF; ” 
year = (Lime *» 25) £ 0x7F}+1980 Pr ite 25038 67 
fixdig¢ning, ninutes, 23 
tindigtsees, seconds, 2 
Printf(Ks Ra:Kesks on Ra/Hd/zA\n", string, hours, mins, 
secs, month, dby, year); 
> 
For another example of this function, see the entry for time. 
See Also 
Gettime, Ksettime, time, TOS, xbios 
Notes 
The time dats in the bit map used by Settime is in exactly the reverse order of 


the data used by the gemdos funct 
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shel_cavea—AES function (Libaos.a/shel_eayrn) 
Search for an environmental variable 
#include <aesbind.h> 
int shel_envrn(parameter, name) char * parameter, *name, 


shel_enven is an AES routine that searches for a particular environmental vari~ 
able. name points to the name of the variable for whose value you want; note 
that the name must end with an equal sign ‘=". parameter points to the byte im- 
mediately following the value of the variable, shel_enyrn always returns onc. 


vee Also 
AES, TOS 


shel_find—AES function (libaes.a/shel_find) 
Search PATH for file name 
include <aesbind.h> 
int shel_find(pathname) char “pathname; 


shel_find is an AES routine that does searches for a file in the directories 
named in the PATH environmental variable, pathname points ta the name of 
the file being sought; shel_find changes this name to the full path name of the 
file if it is found, shel_find returns zero if an error occurred, and a number 
greater than zero if one did not. 


See Also 
AES, PATH, TOS 


shel_read—AES function (libaes.a/shel_read) 
Let an application identify the program that called it 
include <aesbind.h> 
int shel_read(command. tail) char *command, “tail; 


shel_read is an AES routine that returns the name of the command that in- 
voked the current AES application. command points to the name of the com- 
mand, and tail points to its tail; the values of both are set by this routine 
shel_read returns zero if an error occurred, and a number greater than zero if 
one did not. 


See Also 
AES, TOS 


shel_wrlte—AES function (Iibaes.a/shel_write) 
‘Run another application 
include <aesbind.h> 
{ shel_write(/las, graphic, gem, command, tail) 
int flag, graphic, gem; char *contmand. *1ail: 
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shellsortGeneral function (libe.a/shellsort) 


short Definition 


420 


shel_write is an AES routine that tells AES whether to run another application, 
and, if necessary, which application to run. flag indicates whether to run 
another application: zero, exit to the operating system; one, run another ap~ 
plication. graphic indicates if the application to be run is a graphics applica- 
tion: zero indicates no, and one indicates yes. gem indicates if the application 
to be run is an AES application: zero indicates no, and one indicates yes. 
Finally, command and tail point, respectively, to the command's name and tail, 
shel_write returns zero if an error occurred, and a number greater than zero if 
one did not, 

See Also 

AES, TOS 


Sort arrays in memory 
shellsori(data,n, size, comp) 
char “data; int 1, size; int (*comp)()s 


shellsort is a generalized algorithms for sorting arrays of data in primary 
memory. shellsort uses D. L. Shell's sorting method. shellsort works with a se= 
quential array of memory called data, which is divided into n parts of size bytes 
each. In practice, data is usually an array of pointers or structures, and size is 
the sizeof the pointer or structure, Each routine compares pairs of items and 
exchanges them as required, The user-supplied routine to which comp points 
performs the comperison, It is called repeatedly, as follows: 

Gconpy (pt, £2) 

char *pt, #52; 
Here, pI and p2 each point toa block of size bytes in the data array. In pre: 
tice, they are usually pointers to pointers or pointers to structures. ‘The com= 
parison routine must return a negative, zero, or positive result depending om 
whether pl is less than, equal to, or greater than p2, respectively. i 


Example 
For an example of aow to use this routine, see the entry for string. 


See Also 
ctype, qsort 

The Art of Computer Programming. vol. 3, pp. 84/f, 114ff 
Notes 

shellsortis an iterative algorithm; it does not use much stack. 


A short is a numeric data type. By definition, it cannot be longer than an int 
a long. For Mark Williams C, a short is equal to an int; that is, sizeof short & 
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quals two chars, or 15 bits plus a sign. A short normally is sign extended when 
cast to a larger data type; however, an unsigned short will be zero extended 
when cast. 


See Also 
declarations 


show—Command 
Display a stored screen image 
show screenfile 


show displays a screen image that has been stored with the command snap. 
screenfile is the name of the file in which the screen image is stored. show 
checks to see that screenfile is the correct size, i.e., large enough to hold an en- 
tire screen image (32 kilobytes). If the file is of the wrong size, show exits 
silently. 


See Also 
commands, snap, TOS 


showmouse—Command 
Redisplay the mouse pointer 
showmouse 
showmouse uses the function linea9 to redisplay the mouse pointer. 


See Also 
commands, hidemouse, Line A, TOS 


Header file 
TOS header file 
#include <signal.h> 


signal.h is a header file that defines signals used on the Atari ST. These include 
68000 machine exceptions, trap instructions, and GEM-DOS aliases. 


See Also 
bombs, header file, TOS 


sin—Mathematics function (libm.2/sin) 
Calculate sine 
#include <math.h> 
double sin(radian) double radian; 


sin calculates the sine of its argument radian, which must be in radian measure. 
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Example 

For an example of this function, see the entry for acos. 
See Also 

mathematics library 


sinh—Mathematics function (Iibm.a/sinh) 
Calculate hyperbolic sine 
#include <math.h> 
double sinh(radian) double radians 


sinh calculates the hyperbolic sine of radian, which is in radian measure. 
Example 
For an example of this function, see the entry for cosh. 


See Also 
mathematics library 


size—Command 
Print the size of an object module 
size -aet | file... 


size prints the size of each segment of each given Mark Williams C object 
module file in decimal, plus the total of all the segments in both decimal and 
hexadecimal. All sizes are in bytes. Each file must be a Mark Williams C ob- 
ject module. 


The options are as follows: 
-a Print the size of debug, symbol, and relocation segments as well. 
-e Print the total size of all common areas in each relocatable object module. 


-t At the end, print the total size of each segment summed over all the files; 
no total is printed if only one file is specified. The segmented listed are 
the following: 


shri shared instruction 
prvi private instruction (usually zero) 
chssi uninitialized instruction (usually zero) 
shed shared data 
sped private data 
cbssd uninitialized data 
See Also 


ce, commands, epp, nm, strip 
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sizeof—Definition 
sizeof is C operator that returns a constant int the size of any given data 
clement, The element examined may be a data object or a piece of a data ob- 
ject, or a type cast, sizeof returns the size of the element in chars. 


Note that sizeof is especially useful in malloc routines, and to. specify byte 
counts to 1/0 routines. Using it to set the size of data types instead of using a 
predetermined value will increase the portability your code. 

See Also 

data types, operators 

The C Programming Language, page 188 


sleep—Command 
Stop executing for a specified time 
sleep seconds 
sleep suspends execution for a specified number of seconds. This routine is 
especially useful with other commands to the shell msh, For example, typing 


sleep 3600; echo coffee break tine 
will execute the echo command in one hour (3,600 seconds) to indicate an im- 
portant appointment. sleep operates in two-second increments under TOS, 


See Also 
commands, msh, msleep 


snap—Command 
Save a screen image 
snap screenfile 


snap takes a “snapshot” of the screen's image, and writes it into screenfile. Note 
that screenfile is always 32 kilobytes long; if the disk drive does not have 
enough space to hold a file of this size, snap exits without an error message, 


See Also 
‘commands, show, TOS 


sort—Command 
Sort fines of text 
sort |-bedfimnrul [-t c] |-0 outfilel |-T dirl [+begl-endllfile ...] 
sort reads lines from each file specified, or the standard input if none. Tt writes 
to the standard output in sorted order. The order into which the output is 
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sorted is determined by comparing a key from each line; the key is all or part of 
an input line, depending upon options are selected, By default, the key is the 
entire input record (line) and ordering is by the ASCII collating sequence, ie., 
lower-valued ASCII characters sorted before higher-valued. 


The follo 
ordered. 
<b Ignore leading white space (blanks or tabs) in key comparisons. 


-d Dictionary ordering; only letters, blanks, and digits are considered in key 
comparisons. This is essentially the ordering used to sort telephone direc 
tories. 


1g options affect how the key ig constructed or how the output is 


-f Fold upper-case letters to lower case for comparison purposes. 
“i Ignore all characters outside of the printable ASCII range (040-0176). 


-n This option tls sort that the key is a numeric string, which consists of: 
optional leading blanks and optional minus sign followed by any number 
of digits with an optional decimal point. The ordering is by the numeric, 
as opposed to alphabetic, value of the string. 

-r Reverse the ordering, ic., sort from largest to smallest. 

As noted above, the key compared from each line need not be the entire input 

line. The option +seg indicates the beginning position of the key field in the 

input line, and the optional ~end indicates that the key field ends just before 
the end position, If no -end is given, the key field ends at the end of the line. 

Each of these positional indicators has the form +m.nf or ~m.n/, where m is the 

number of fields to skip in the input line and 7 is the number of characters to. 

skip after skipping fields. Optional flags f are chosen from the above key flags. 

(béfinr) and are local to the specified field. 


The following additional options control how sort works. 


-¢ Check the input to see if it is sorted. Print the first out of order line 
found, 


-m Merge the input files. sort assumes each file to be sorted already. For 
large files, it cuns much faster with this option. 


-0 ouifile 
Put the output into ou/filé rather than on the standard output. This 
allows sort ta wark correctly if the output file is one of the input files. 


-te Use the character ¢ to separate fields rather than the default blanks and 
tabs, 


-u Suppress multiple copies of lines with key fields that compare equally. 
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See Also 
commands 


Diagnostics 
sort returns a nonzero exit status if file opening errors or other internal 
problems occurred, or if the file was not correctly sorted in the case of the -c 
option. 


sprintfSTDIO function (libe.a/printf) 
Format output 

#include <stdio.h> 

sprintf(séring, format [ , arg 

char *siring, * format; 


sprintf uses the string format to specify an output format for each arg: it then 
writes every arg into string, which it ends with NUL. For a detailed discussion 
of sprintf’s Formatting codes, see printf, 


See Also 

printf, sprintf, STDIO 

The C Programming Language, page 150 

Notes 

‘The output string passed to sprintf must be large enough to hold all output 
characters. Because C does not perform type checking, it is essential that each 
argument match its format specification, 


sart—Mathomaties function (libm.a/sqrt) 
Compute square root 

#include <math.h> 

double sqrt(=) double 


sqrt returns the square root of 2. 


Example 

For an example of this function, see the entry for cell 

See Also 

mathematies library 

Diagnostics 

A domain error in sqrt (z is negative) sets erruo to EDOM and returns 0 


srand—General function (libe.a/srand) 
Seed random number generator 
srand(seed) Int seed, 
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sscanf—STDIO function (libe.a/scant) 


stack—Definition 
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srand uses seed (0 initialize the sequence of pseudo-random numbers returned 
by rand, Unequal values of seed initialize different sequences. 


Example 
For an example of how to use this function, see the entry for rand. 


See Also 
rand 
The Art of Computer Programming, vol. 2 


Format input 

#include <stdio.h> 
sscanf(string, format [, arg }...) 
char *string; char *format; 


sseanf reads the argument string, and uses format to specify a format for each 
arg, each of which must be a pointer. For more information on sscanf’s con- 
version codes, see scanf. 


See Also 
STDIO 
The C Programming Language, page 150 


Notes 

Because C does not perform type checking, an argument must match its format 
specification, sscanf is best used only to process data that you are certain is in 
the correct data format, such data that were previously written out with sprintf. 


‘The stack is the segment of memory that holds function arguments, local 
variables, function return addresses, and stack frame linkage information. 
Neither the 68000 nor the Atari ST support dynamic stack resizing, so programs. 
run on the ST havea fixed segment allocated to the stack at run time, 


‘The Mark Williams C runtime startup routine allocates _stksize bytes of stack 
when a program is executed, and sets the 68000 stack Sointer register, a7, to 
point at the highest address in this segment. _stksize is then assigned a poiater 
to the lowest address that the stack pointer may reach before the stack begins to 
overwrite program data, _ stksize is set to two kilobytes by the Mark Williams 
C library, Tt may be set t0 another value by including an initialized declaration 
for it in your program; for example 


long _stksize = 16000; 
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sets the stack size to 16,000 bytes. 


‘The value of _stksize must be even, The size of the stack cannot change once 
your program has begun to execute because the allocation must be made before 
the stack is used and your program uses stack as soon as it begins to execute. 


Af your program wes recursive algorithms, or declares large amounts of 
automatic data, or simply contains many levels of functions calls. the stack may 
“overflow", and overwrite the program data. You can check for stack overflow 
very simply, The runtime startup reinitializes the long _stksize to point to an 
address that the stack should not reach, You can compare _stksize to the ad- 
dress of the last automatic variable in any function; as long as _stksize is le:s 
than the address of that automatic function, you are safe. 


Example 
‘This example checks for stack overflow; it aborts the program and prints a mes- 
sage when overflow occurs. The main routine prints the location of its ar- 
guments, calls the stack overflow routine, and then calls itself recursively. For 
another example, see the entry for Fgetdta. 


_stheeste 
int 
if (Clong)&i <= _stksize) ¢ 
puts [stack overflow): 


exits 
y 


rainterge) int argc; ¢ 
extern long _stksize; 
printfterge et 3lx\n", Barge); 
_stktest 0); 
Beincarse): 
> 
‘See Also 
“stksize 
Notes 
‘TOS pushes data onto the user stack; therefore, you should make sure that your 
stack has a cushion of at least 128 bytes to hold these data when your progeam 
enters the system, 


standard input—Definition 
The standard input is the device from which data are accepted by default; it is 
defined in the header file stdio.h under the abbreviation stdin, and will be the 
computer's keyboard unless redirected by msh or freopen, 
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See Also 
freopen, header file, msh, standard output, stdio.h 


standard output—Definition 


‘The standard output is the peripheral device upon which programs write output 
by default. It is defined in the file stdio.h under the abbreviation stdout, and in 
most instances is defined to be the computer's monitor. 

See Also 

header file, standard input, stdio.h 


stat.h—Header file 


Definitions and declarations used to obtain file status 

#include <stat.h> 

stat.h is a header file that contains the declarations of several structures used by 
the routines fstat and stat, which return information about a file's status. 

See Also 

istat, header ile, stat 


stat~General function (libe.a/stat) 
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Find file attributes 

#include <stat-h> 

stat( file, statpir) 

char *file; struct stat *stal pir; 


stat returns a structure that contains the full GEM-DOS attributes of a file; 
note that the listing shown by the command does not describe attributes fully. 
file points to the path name of file, and statpir points to a structure of the type 
stat, as defined in the header file stat.h. 


The following summarizes the structure stat and defines the permission and file 
type bits. 
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struct stat ¢ 
ev tat dev; 
inte st ino; 
Unsigned shore st mode; 
short st_nlink; 
short st uid: 
short st sid? 
ev.t st_rdev; 
size t et size; 
tine_t st_atine: 
inet st ntine; 
tine_t at_etine; 


# 


‘define $_19ROH 0x01 / Read-only */ 
define S_AJAID 0x02 (J Widéen fron search */ 

‘eet tne SLLVSYS 0x0 ‘J system, niacen trom searen */ 
define S1VOL 0x08 7 Volume’ Label in First 11 bytes */ 
define $101k O«10 7 Directory */ 

define $ 1uAC 0x20 7 Weitten to and closed */ 


Entries in the structure stat are there to preserve compatibility with the 
COHERENT operating system. Most return meaningless values when used on 
the Atari ST, with the following exceptions: st_atime, st_mtime, and st_ctime 
all return the time that the file or directory was last modified; st” size gives the 
size of the file, in bytes; and st_mode gives the mode of the file, & described in 
the entry for Is, 


See Also 
fstat, Is, msh, open, stat.h 


Diagnostics 
stat returns -1 if the file is not found. 


static—Definition 
static is a C storage class, 


A static variable resembles an extera in that it does not disappear when its 
calling function exits, Unlike an extern, however, a static variable is “private”: 
when internal to a function, it can be accessed only by that function; when used 
external to a function, it can be accessed only by functions that are defined 
within the same source file as that variable. This helps to avoid name conflicts; 
for example, if a program consists of two files, each of which has a variable 
named foo, declaring each foo to be static keeps them from being written into 
each other. 


Functions that are used locally can also be declared to be static: this helps to 
prevent name conflicts when assembling programs from a number of different 
sources, such as libraries from a variety of vendors and modules written by dif- 
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‘stdin—Definition 


STDIO—Overview 
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foront programmers, 
See Also 

auto, extern, register variable, storage class 
The C Programming Language, page 80 


stdin is an abbreviation for standard input. It is defined in the header 
stdio.b, 


See Also 
stdio.h, standard input 


‘STDIO is an abbreviation for standard input and ourpui. It refers to a set of 
standard library functions that accompany all C compilers and that govern input 
and output with peripheral devices. 


Mark Williams C includes the following STDIO routines: 


clearert Present status stream 

exit Leave a program gracefully 
felose Close a stream 

fdopen Open a stream for 1/0. 

feof Discover a stream's status 
ferror Discover a stream's status 
flush Flush a buffer 

fgete Get a character 

fgets Geta string 

fgetw Get a word 

fileno Geta file descriptor 

fopen Open a stream 

iprintf Format and print to a file 
{pute Output a character 

puts Output a string 

fputw Output a word’ 

fread Read a stream 

{reopen Open a stream 

fscanf Format and read from a file 
fseck Seek in a stream 

ftell Return file pointer position 
fwrite Write to a stream 

gete Get a character 

getchar Get a character 

gets Get a string 

getw Get a word 
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pute Output a character 
putehar Output a character 

puts Output a string 

putw Output a word 

rewind Reset a file pointer 

scant. Format and input from standard input 
setbuf Set alternative stream buffers 

sprintf Format and print to a string 

sscanf Format and read from a string 

ungete Return character to input stream 


Note that STDIO routines are buffered by default. 


See Also, 
buffer, FILE, Lexicon, stdio.h, stream 
The C Programming Language, page 166 


stdio.h—Header file 
stdio.h is a header file that defines several manifest constants used in I/O, such 
as NULL and FILE, declares the STDIO functions, and defines numerous 1/0 
macros. 

Seo Also 

header file, manifest constant, STDIO 


stdout—Definition 

stdout is an abbreviation for standard output; it is defined in the header file 
stdio.h. 

Sée Also 

standard output, stdio.h 


stime—Time function 

Set the time 

#include <time.h> 
stime(timep) time_t *timeps 


stime sets the system time, which Mark Williams C defines as being the number 
of seconds since midnight of January 1, 1970, Oh0Om00s GMT. The argument 
timep points to the new system time, which is of the type time_t; this is defined 
in the header file time.h as being equivalent to aa long. 
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Example 
For an example of using this function from the \auto directory, see the entry 
for \auto. 


See Also 
date, time 


Diagnostics 
stime returns ~1 on error, zero otherwise. 


_stksize—External data 
_stksize is an external symbol that sets the size of the stack. It is defined in the 
‘Mark Williams Company libraries as being equal to two kilobytes, which is more 
‘than enough stack for most applications, 


If you wish to have more stack, insert into main the declaration 
long _stkeiz 
where n is the number of bytes required. must be even. 


Example 
For an example of how to use this variable in a program, see the entry for 
memory allocation. For an example of a program that uses _stksize to check for 
stack overflow, seo the entry for Fgeidta. 

See Also 

Id, stack 


storage class—Definition 
Storage class refers to the part of a declaration that indicates how data are to be 
stored. The legal storage classes are as follows: 
auto 
extern 
register 
static 
typedef is technically defined as a storage class as well, but it does not actually. 
indicate how data are stored. The default class is auto, 
See Also 


auto, extern, register, static, typedef 
The C Programming Language, page 192 


streat—String function (libe.a/streat) 
‘Append one string to another 
char *streat(scring/, string2) char *siring1, *string2; 
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streat appends all characters in string? onto the end of siring/. It returns the 
modified string!. 


Example 
See string. 


For an example of this function in a TOS application, see the entry for Fgetdta. 
See Also 

string, strocat 

The C Programming Language, page 44 

Notes 

string! must contain enough space to hold itself and string2. 


stremp—String funetion (lihe.a/stremp) 

‘Compare two strings 

stremp(siringd, siring2) char *siringl, *string2 

stremp compares siring! with string? lexicographically. It returns zero if the 
strings are identical, -1 if string! occurs earlier alphabetically than séring2, and 
one if it occurs later. This routine is compatible with the ordering routine 
needed by qsort. 

Example 

See string and malloc, 


See Also 
gsort, string, strnemp 
The C Programming Language, page 101 


String function (libe.a/strepy) 
Copy one string into another 
char *strepy(siring!, string2) char *siring!, *string2; 


strepy Copies the contents of sérinig2, up to the NUL character, into string, and 
returns string]. The order of the arguments is reminiscent of an assignment 
statement, 


Example 
See string. 


For an example of using this function in a TOS application, see the entry for 
Fpetdta. 
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string—Overview 
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See Also 

String, strnepy 

The C Programming Language, page 100 

Notes 

string] must contain enough space to hold string2. 


‘The term stream applies to any entity that can be named and through which bi 
can flow, such as a device or a file. The name “stream” reflects the fact that in 


the C programming environment eschews record descriptors and other devices. 
that predetermine what form data assumes; rather, data, from whatever source, 
are seen merely to be a flow of bytes whose significance is imposed entirely by 
the context that the calling program creates. 7 


See Also 
bit, byte, data formats, file 


‘The character string is a common structure in C programs. The runtime 
representation of a string is an array of ASCII characters that is terminated by a 
NUL character (*\0"), Mark Williams C uses this representation when a proj 
contains a string constant, for example: 


"1 am a. steing constant 


The address of the first character in the string acts as the starting point, 0 
“handle”, of the string; note that a pointer to a string is nothing more than this 
address. Note, too, that an array of 20 characters holds a string of 19 (not 20) 
non-NUL characters; the 20th character is the NUL that terminates the string. 


‘The following routines are available to help manipulate strings: 


index search fora character 
rindex search for a character 
strcat concatenate a string 
stremp compare two strings 
strepy copy a string 
strlen measure a string 
strncat concatenate a string 
strnemp compare two strings 
stenepy copy a string 

Example 


This example reads from stdin up to NAMES names, each of which is no mo 
than MANLEN characters long, It then removes duplicates names, sorts thé 
names, and writes the sorted list ta the standard output, Tt demonstrates th 
functions stecat, stremp, strepy, and strlen, 
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erpolude <stdfocte 
define Wuawes 512 
feat ine MAKLEN 60 
har *array (NAMES); 


har fIrStIMAXLEND, midHAKLEN , Last OHRMLEKI 
har "space =" 


cxtern ine streamed: 
extern char Ystreat(); 


main) 
register int index, count, inflass 
register char *nane; 


count = 9; 
while (scant(is %e Ke\n 
strest(finer, ope: 
streataid, space 
nane = strcat(first, Cstreat¢nid, last))): 
inflag = 0; 
for Cindox=0; index < count; indext+) 
if Getremptarray indexd, name) == 0) 


first, mid, last) 


inflag = 13 

Sf Ginflag == 0) € 
sreayteount) = mallocteerlentname) + 19) 
strepyCarrayleount) , rane 
counts; 

> 


> 


shellsort(array, caunt-1, sizeofcchar *), stream); 

for Cindex=0; index < count; indexes) 
printfc"e\n", array index )2 

exit: 


streonp(st, $2) 
fegister char *¥s1, #52; 
‘ 


extern int strenp(; 
return(strenet*st, "5219; 

: 

See Also 

ASCIT, Lexicon 


strip—Command 
Strip symbol table from object file 
strip ~des file 
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strip removes the symbol table, relocation information, and debug tables from 
each object file specified. strip effects reasonable savings on systems where file 
space is at a premium. 


strip recognizes the following options: 
-d Keep debug information, 

Keep relocation information, 
Keep symbols. 


See Also 
ce, commands, 1d, nm 


Notes 
strip should be used only on fully linked files, 


strlen—String function (libe.a/strlen) 
Measure the length of a string 
strlen(siring) char “string; 


strlen measures string, and returns its length in bytes, not including the NUL 
terminator. This may be useful in determining how much storage to allocate for 
astring, 

Example 
For an example of how to use this function, see the entry for string, For an ex= 
ample of using this function in a TOS application, see the entry for Fgetdta. 
See Also 

string 

The C Programming Language, page 95 


strneat—String function (libe.a/stencat) 
Append one string to another 
char *strncat(string/, string2, n) 
char *siring |, *siring2; unsigned 1; 
strneat copies up to 1 characters from siring2 onto the end of string/. Tt stop 
when # characters have been copied or it encounters a NUL character in 
string2, whichever occurs first, and returns the modified string 7. 


See Also 
streat, string 
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Notes 
siring! should contain enough space to hold itself and m characters of siring2, 


«stencmp~String function (libe.a/strnemp) 
Compare two strings 

strnemp(string J, string 2, n) 

char “string, *string2; unsigned 1; 


sirnemp compares lexicographically the first bytes of string? with string? 
Comparison ends when bytes have been compared, ot a NUL character en- 
countered, whichever occurs first. strnemp returns zero if the strings are iden 
tical, -1 if string] occurs earlier alphabetically than string2, and one if it occurs 
later. This routine is compatible with the ordering routine needed by qsort, 


Example 
For an example of the related string-handling function stremp, see the entry for 
string 


See Aiso 
strcmp, string 


strnepy~String function (libe.a/strnepy) 
Copy one string into another 

char *strnepy(string 1, string2, n) 

char “string, *string2; unsigned 1; 


stnepy copies up to n bytes of string? into string?, and returns string /. Copying 
ends when 7t bytes have been copied or a NUL character has been encountered, 
whichever comes first. If string? is less than n characters in length, string? is 
padded to length with one or more NUL bytes. The order of the arguments is 
reminiscent of an assignment statement, 

Example 

For an example of the related string-handling function strepy, see the entry for 
string, 

See Also 

strepy, string 

Notes 

string] should have enough space to hold itself and n characters of string2. 


Struet—Definition 
struct is a C keyword that introduces a structure. The following is an example 
of how struct can be used in the description of a name and address file: 
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structure assignment—Definition 
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struct address ¢ 
char firstname 10); 
char lastname 1527 
char 
char 
char state(2} 
char 2iptS); 
int salescede; 


% 
‘The definition of C in The C Programming Language prohibits the assignment 
of structures, the passing of structures to functions, and the returning of st 
tures by functions, Mark Williams C allows structures to be assigned, provided 
they are of the same type, and allows structures to be passed and returned from 
functions, These features are supported by most compilers, but users should 
aware that their use can cause problems in porting code to some compilers. 


See Also 
array, field, structure 
The C Programming Language, page 119 


A structure is a set of variables that has been given a name and can be worl 
with asa single entity. The variables may be of different data types. Structur 
are a convenient way to deal with data elements that belong together, such a 
names and addresses, employee descriptions, or sales and inventory informatios 
See Also 

field, record, struct 

The C Programming Language, page 119 


The C Programming Language forbids structure assignment, the passing 
structures to functions, and returning structures from functions (as opposed: 
the passing or returning of pointers to structures). Mark Williams C lifts thes 
restrictions. 


Some other C compilers modify structure arguments and structure returns to b 
Structure pointers, Note that the use of structure assignment, structure 

guments, Or structure returns may create problems when porting the code f0 
another computing environment. 


See Also 
structure 
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Environmental parameter 
SUFF names a set of suffixes that msh will automatically append to command 
names, The suffixes are appended to the given command name when searching 
the directories named in the PATH environmental veriable. For example. 
typing 

setenv PATHS\BIn, ,\Uib 
setenv SUFFs, org, .t08,.ttp 
means that when you give msh the command 


foo 


i will look for a file with one of the following names: 


\win\foo 
\pin\foo.pra 
\bin\foo.tos 
Awin\Foo. tte 
foo 

foo.pre 
fo0.t0s 
fo0.ttp 
\Uib\ too 
\Uib\foo.prg 
\Uib\foo.tos 
\ubytoo-cep 


The file names are searched for in the arder given above, and msh stops sear 
ching after finding the first file that matches the requested pattern. 


Lis set the with seteny command, 


See Also 
msh, seteny 


Super—gemdos function 32 (osbind.h) 
Enter supervisor mode 
Jong Super(stack) char *stacky 


Super manipulates the Atari ST's supervisor mode, which, in theory, must be 
obtained before the extended BIOS routines can be used. stack poinis to a new 
supervisor stack. Tf the machine is presently set in user mode, it switches to su~ 
bervisor mode; if in supervisor mode, it returns to user mode, 

Example 

This example changes the floppy write verify flag so floppy writes are not 


automatically verified. This speeds up processing, but can be dangerous, and is 
not recommended. 
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include <osbind.h> 
define FVERIFY (short *) OxO444L) 


sain) ¢ 
long save ssp; 


save_ssp = Super(Ol); /* Switch to system mode */ 
sEVERIFY = 0; 7 Clear the word. */ 
super (save s5p)z 7 Restore systen */ 

y 

See Also 

gemdos, TOS 

Notes 


Super has been documented elsewhere as returning the supervisor/user 
flag if stack is set to -1L; however, it crashes the system instead. With syster 
that have TOS in ROMS, stack should be set to one to perform this task. 


‘Supexec—xblos function 38 (osbind.h) 
Run a function under supervisor mode 
#include <osbind.h> 
#include <xbios.h> 
unsigned long Supexec(address) 
int "address; 


Supexee invokes supervisor mode, and allows you to run a routine under it. ad= 
dress is the address of the function to be run. 


‘The Supexec function has two features that are not widely known but co 
prove useful in your programs, 


The first is that any value returned by function run under under Supexee i 
returned untouched by the xbios trap. 


Example 

‘The following example uses the return value of a function run under Supexee 
time execution speeds: 4 
Ut Redefine Supexect) function to get long return vatue */ 
Finclude <osbind.h> 

undef Supers 

eetine Supexec(a) xbios(38,a) 


JF Return the system 200 hz timer tick count */ 
long read_tieks() € retumn *¢cleng *30xibad; 2 
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J Return microseconds that (*f)() takes to execute */ 
ong time funetionc#y int C907 
G 


register int ntines = 4*5*1000; 
long tetart = Supexec(read ticks): 

while (-ontines >= 0) A902 

Feturn (Supexec(read ticks) ~ tetart +2) >> 2: 


i} 


J* Sone functions to tine *7 
rutl_finction®) € return; > 

int Te = Ox0125, ib = ox3210; 
int ret_functionc) ¢ return’ 
int fede functionc) € return 
nt isup_function() ¢ return 
fine imul_funetionc) € return 
int idivifuneeiang) € return 


long Lret_funct font) ¢ return 
long Ladd funct ient) € return 
long [sub function) € return 
lang. tmul_funct onc) € return 
long Idivifunetionc) ¢ return 


souble do = 2540.0, & = 4321.0; 
souble dret_function() ¢ return da,d; > 
souble dadd_function() « return daveb; 

chuble dsub_funetion() € return da-db; 
couble dul_funetion() € return data; 
cbuble diiv_funetion®) € return de/db; 


7" Report the tines for the functions #/ 

mind € 
printf tnull ld microseconds\nt, tine functiantnul _functiand): 
printfCtiret ld mieroseconde\n", tine_funct fontiret_function)): 
printf("iadd ld microseconds\n", tine funct font iadd_funetion)); 
Printf(itisub ld microseconds\n', tine_funct font isub_ function) 
printf(vimul ld microseconds\n', tine_funct font mul_funct an) 
Printf(Widiv Xd microseconde\n", tine_function(idiv funetien)); 


printf(*Lret 21¢ microseconds\n", tine_function(Lret_functien)); 
Print#(itLadd Sls mierosesende\nt, tine_funetiang (ade Funes ion) 
DBrint¥(*Lsub Xd microsecends\n", tine funetian( sub function); 
Printf{C*imil Xld microseconds\n", tine_function( nul function) 
printf(Wiaiv Xld micraseconds\n", tine_function(iiv function); 


Mark Williams C “i 


Syersion Lexi 


printf(idret ld microsecande\n", time_funct ontdret_funet ion); 
Brint (decd iid micraseconds\n", tine _funet ion(dadd_ Funct fon?) 
Brintf(dsub {ld microseconde\n", tjne_function(dsub_funct {on)); 
printf(Venul 31d microseconds\n", time_funet ionCdmul_funct ion)); 
printf("adiv Sid micraseconds\n", time_funct ion(ddiv_funetion)3 
return 0; 


5) 


‘Phe second feature is that a function run under Supeyee can be passe 
parameters by including them in the call to the xbios trap. The first paramet 
to the function will always be a long pointer to itself. Any subsequei 
parameters will be available if they are declared in normal C style. 


Example 
‘The following example passes three arguments to a function run under Supexec 
to copy a block of low memory to a user-supplied buffer. 


‘/* Redefine Supexect) to pass 3 araunents */ 
include <osbind.t> 

fundef Supexee 

itdetine Supexec(s,b,c,d) xbios(38,2,b,¢,4) 


/* Word copy function with urmy parameter */ 
‘supercopy(sel,destp,srep,nuds) register int (#self)0, *destp, “srep, mds; 
« 

while Cems 2= 0) *aestpet = “arepiey 
> 


1 copy the process durp area to our dete space and print it */ 
rraing 
int proct6a;/* Kore or less */ 
Supenec supercopy proc, OxS80L 84; 
for = 0; i < 64; i424) 
prinef(wniex Wx Wix WON", proetid. precti+l], proeti+2), 
proctia31); 


return 


> 


See Also 
TOS, xbios 


Sversion—gemdos function 48 (osbind-h) 
Get the version number of TOS 
+#include <osbind,h> 
int Sversion() 


Sversion gets and returns the current TOS version number, 
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Example 
This example prints the TOS version number on the standard output. 


include <osbind. b> 


ain) € 

unien ¢ 
struct € 
Unsigned ninors8; 
unsigned sejoes8; 
> braker 
int al 

2 versa 


vyersn.all = sversion(; 
print(T0S/SENDOS version 32K revision %2x.\n", 
Versn.braier.nejor, versn, brake 


» 


See Also 
gemdos, TOS 


swab—General function (libc,a/swab) 
‘Swap a pair of bytes 
swab(sre, dest, nb) char *src, *dest; unsigned nbs 


The ordering of bytes within a word differs from machine to machine, This 
may cause problems when moving binary data between machines. swab inter- 
changes each pair of bytes in the array src that is n bytes long, and places the 
result into the array dest, The length nb should be an even number, or the lest 
byte will not be touched. src and dest may be the same place. 

See Also 

byte ordering 


system—General function (libe.a/system) 

ass a command to TOS for execution 
i system( commandline) char *commardline; 
system passes commandline to the Mark Williams shell, which foads it into 
memory and executes it. system executes commands exactly as if they had been 
typed directly into the shell, 
Example 


This example uses the system function to list all C programs in the present 
directory. 
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maine € 
‘extern Int system); 
systen¢techo [8:21*-089; 

> 

See Also 

exit, msh, Pexec 


Notes 
No shell variable that has been set with the set command is duplicated, 
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‘The TOS operating system uses a numbet of “magic locations” where it sto 
key system variables. By using the peek and poke routines included with Ma 
Williams C, you can alter these variables directly, to customize TOS more 
closely to your needs and tastes. 

Note that you can safely manipulate the address 0x0 to 0x800 only when y 
program is in supervisor mode; you can enter superviscr mode by calling tl 
gemdos function super. 


The following table gives each “magic location”, the common Atari mnemonic 
for it (should you wish to build a header file to work with these locations), th 
longth of the system variable, and a brief description. 
0x400/ety_timer/long 
Points to the timer event handler. 
0x404/ety_critic/long 
Poirits to the critical error handler, 
0408 /ety_term/tong 
Poinits to routine that ends a program. 
0x420/memyalid/int 
Check if the memory controller's configuration is valid. 
0x424/memetrl/int 
Copy of configuration value in memory controller. 
0x426/resvalid/long 
If proper value given, jump is made to reset routine pointed to by addr 
0x42. 
0x42A/resvector/long 
Address of reset routine, 


0x42E/phystop/long 
Top of RAM. 
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0x432/_membot/long 
‘Points to beginning of transient program area. 
0x436/_memtop/long 
Points to end of transient program area, 
043A/memyal2/long 
This if set properly, declares memory configuration to be valid. 
43E/flock/int 
If set to a value other than zero, disk access is in progress, 
0x440/seekrate/int 
Set disk drive seck rate, as follows: zero, six millisecon 
milliseconds; two, two milliseconds; and three, three milliseconds. 
0x442/_timer_ms/int 
‘Glock rate, in microseconds. 
0x444/_fyerity/intn 
If set to a value other than zero, every disk write access is verified. 
0x446/_bootdey/int 
‘Number of disk drive from which operating system was loaded. 
0x448/palmode/int 
IE set to a value other than zero, system is in PAL mode (50 Hz); other- 
wise, system is in NTSC mode, 
0x44A/defshiftmod/int 
if Atari shifted from monochrome to color, new resolution is set here: 
zero indicates low resolution; one, medium resolution. 
0x44C/sshiftmod/int 
Screen resolution, as follows: zero, low resolution; one, medium resolu- 
tion; two, high resolution. 
0x44C/_y_bas_ad/long 
Poin to Togical screen base. Address always begins on a 256-byte boun— 
dary. 
0x452/vbisem/int 
If set to zero, vertical blank routines are not executed. 
Ox454/nybis/int 
‘Number of vertical blank routines queued for execution, 
0x456/_yblqueue/long 
Points to the list of routines queued to be executed during vertical 
blanking. 
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0x45A/colorptr/long 
If other than zero, holds pointer to color palette to be executed duri 
next vertical blank, 
0x45E/screenpt/long 
Point to beginning of video RAM. 
0x462/_ybelock/long. 
Number of vertical blank interrupt routines. 
0x466/_freclock/long 
Number of vertical blank routines executed. 
0x46A/hdy_init/long 
Point to hard-disk initialization. 
0x46E/swr_vee/long 
Point fo routine to change screen resolution. 
0x472/hdy_bpb/long 
Point to fetch BIOS parameter block for hard disk. 
0x476/hdy_rw/long 
Poinf to read/write routine for hard disk. 
0x47A/hdy_boot/long 
Point To routine to reboot hard disk. 
0x47E/hdy_mediach/long 
Point to routine to handle medium change for hard disk. 
0x482/_comload/int 
If'set to a value other than zero, system will attempt to load file com- 
mand.prg after TOS has been loaded. 
0x484/conterm/char J 
Set console attributes. This is a byte-length bit map, whose first four bi 
signify the following: bit 0, toggle key click; bit 1, toggle key repeat; bit 
2, toggle bell when <ctrl-G> is typed; and bit 3, toggle returning Kbshi 
in bits 24-31 for the Function Conin, 
0x486/trpt4ret/long 
‘Return address for call to trap 14. 
Ox48A/criticret/long 
Return address of critical error handler. 
Ox48E/themd/4 longs 
“Memory deseriptor filled by function Getmpb. 
Ox4A2/sayptr/long 
Pointer to save area for process registers after a BIOS call. 
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0x4A6/_nflops/int 
Number of floppy disk drives. 
0x4A8/con_state/long 
Point to screen output routine, 
Ox4AC/save_row/int 
Save cursor line temporarily when moving cursor with cesc>Y. 
0x4AE/sav_context/long 
Point to temporary areas used by exception-handling routines, 
0x4B2/_bufl/2 tongs 
Pointers to heads of buffer lists: first points to head of data sector fi 
second points to head of FAT (file allocation table), 
Ox4BA/_hz_200/long 
Counter For 200-Hz system clock. 
0x4BC/the_eny/4 chars 
Default environment string, four NULs. 
0x4C2/_drvbits/long 
Bit map indicating connected drives: bit zero indicates drive A:, bit one 
indicates drive B:, etc, 
0x4C6/_dskbufp/long. 
Pointer to |,024-byte disk buffer. 
Ox4CA/_autopath/long 
Polnter to autoexecute path. 
Ox4CE/_ybl_list/8 longs 
of pointers to standard vertical blank routines. 
Ox4EE/_dumpfig/int 
If Set to one, a dump of the current screen is sent to the printer port. 
Dump can be aborted by typing help and alt Keys simultaneous! 
Ox4F0/_prtabt/int 
Printer abort flag due to time-out. 
Ox4F2/_sysbase/long 
Pointer to beginning of operating system, 
Ox4F6/_shell_p/long 
Pointer to global shell information. 
Ox4FA/end_os/tong 
Pointer to end of operating system. 


Ox4FE/exee_os/long 
Pointer to start of AES. 
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Example 
The following example pokes address (x484 to turn off the key click: 


ning) € 
pokeb(Ox8éL, peekbCOxtBAL) & ~19; 
3 


See Also 
‘memory allocation, peekb, peekl, peekw, pokeb, pokel, pokew, TOS 
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tail-Command : 
Print che end of a file 

tail [4albell] [file] 

tail [-nlbell] [file] 


tail copies the last part of the specified file, or of the standard input if none, to 
the standard output. 


‘The given number tells tail where to begin to copy the data. Numbers of the 
form +number measure the starting point from the beginning of the file; those 
of the form ~number measure from the end of the file. 


A specifier of blocks, characters, or lines (b, ¢, or I, respectively) may follow 
the number. If no number is specified, a default of -10 is assumed, 

See Also 

commands 

Noles 


As tail buffers data measured from the end of the file, large counts may not 
work. 


tan—Mathematics function (Itbm.a/tan) 
Calculate tangent 

#include <math.h> 

double tan(radian) double radian; 

tan calculates the tangent of its argument radian, which must be in radian 

measure, 

Example 

For an example of this function, see the entry for acos. 

See Also 

mathematics library 


Diagnostics 


tan returns a very large number where it is singular, and sets errno to 
ERANGE. 


‘ah—Mathematics function (libm.a/tanh) 
Calculate hyperbolic cosine 

#include <math,h> 

double tanh(radian) double radian; 
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tempnam—General function (libe.a/tempnsm) 


tetd_to_tm—Time function (Iibe.a/tetd_to_tm) 


tanh calculates the hyperbolig tangent of radian, which is in radian measure, 


Example 
For an example of this function, see the entry for cosh. 


See Also 
mathematics library 


Diagnostics 
tanh sets errno to ERANGE when an overflow occurs 


Generate a unique name for a temporary file 

char *tempnam(directory, name) 

char "directory, *name; 

tempnam constructs a unique temporary name that can be used with 
program. 

directory points to the name of the ditectory in which you want the tempos 
file written. If this variable is NULL, tempnam reads the environmental 


given, tempnam uses \tmp. 

name points to a string of letters that you want to prefix the temporary 1 
this string should not be more than a few characters, to prevent truncation 
duplication of temporary file names. If name is NULL, tempnam will set it to 


If all goes well, it returns a pointer to the temporary name it has written; oth 
wise, it returns NULL if the allocation fails or if it cannot build a temporar 
file name successfully. 

See Also 

environment, mktemp, msh, tmpnam 


~ Convert IKBD time to system calendar format 

#include <time.h> 
tm_t*tetd_to_tm(time) tetd_t rime; 
tetd_to_tm converts the time setting for the intelligent keyboard, as ret 
by the flinction Gettlme, into the system’s calendar format. 


time is of type tetd_t, which is defined in the header file time-h as beié 
equivalent to an unsigned long. It holds the 32-bit map returned by Geiti 
For information on what the bits of this map signify, see the entry for Gettime: 
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fetd_to_ tim returns @ pointer to the structure tm_t, which is defined in the 
header file time.h, For more information on this structure, see the entry for 
time. 

See Also 

time, time.h, tm_to_tetd 


“Tgetdate—gemdos function 42 (osbind.h) 
Get the current date 
‘include <osbind.h> 
int Tgetdate() 
‘Tgetdate gets the current date from TOS. It returns an integer whose bits in- 
dicate the following: 
O-4 day (1-31) 
5-8 month (I-12) 
9-15 year (0-119, 


1980) 


Example 

‘This examples demonstrates both Tgetdate and Tgettime, Note that the time 
returned by this example will be one hour earlier than the time returned by msh 
if the latter is adjusting for daylight savings time. 

Hinelude <esbind. he 


maine) € 
unsigned int dat 
unsigned int tine; 


date = Tyetdatec: (ff Get systen date */ 
tine = Toate ina() 7° Get systen tine */ 
‘meprinecThe Tos tise 1s", vine)? 
dateprint("The TOS date is", date); 


> 


Void fixdigctut, number, size) 
char buf 
ine onunber; 
int size 


register long Limie: 
register Long rember; 


int 9; 
number 

Uinit = 10; 

for (o = 1; 0 < size ; ont) 


Linfe #105 
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$f Cerumber >= Uimte> | [Kpumber 499) € 


for (0 = 0; © < size; of) 
Souter = oy 
buf = 0; 
returny ! 
> 
for (o = 0; 0 < size; or) € 
Limit f= 10; 
-enunbor/Linit; 
umber = numbers init; 
> 
tout = 0 


EY 


tineprine<string,, time) 
char ‘string: 
register unsigned int tines 


c 
int seconde: 
nt hours; 
char mins (3); 
char secs(3); 
tine & Ox001F) << 4; se pits 0: 47 
= Cem >> 59. 8 On3F; Ye bie 5:10 */ 
(eine >> 119 & Dele; 7 Bite 145 97 
Fixdig¢mine, minutes, 20; 
fiadigcsecs, seconds, 2); 
print f(s Mésks:4s\n", string, hours, mins, secs); 
* 


dateprint(string, cate) 
shar string; 

Unsigned int’ date; 

€ 


int year; 
nt month; 


Sint day: 


day = date & OxtF; 

Inonth = (9te>95) & Ox0F; 

year = ((date>r9) & Ox7F) + 1980; 

Printfcmis %4/%a/td\nl", string, month, day, year); 


y 
For another example of this function, see the entry for time. 
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See Also 
gemdos, time, Tsetdate, TOS 


‘Tgettime—gemdos function 44 (osbind.h) 
Get the current time 
#include <osbind.h> 
int Tgettime() 


Tgettime obtains the current time from the operating system. It returns the 
time encoded in the form of an integer whose bits mean the following: 


0-4 number of two-second increments (0-29) 
5-10 number of minutes (0-59) 
11-15 number of hours (0-23) 


Example 

For example of how to use this function, see the entries for Tgetdate and time. 
See Also 

gemdos, time, Settime, TOS 


‘Tiekeal—bios function 6 (osbind.h) 
Return system timer’: calibration. 
+#include <osbind.h> 
#include <bios.h> 
long Tickeal() 
Tickcal returns the system timer's calibration, rounded to the nearest 
millisecond, 
Example 
This example demonstrates Tickeal. Also see the example in the entry for time 
include <osbind.h> 
rain¢) 
« 
printfc"system clock ticks once every Kld meee.\nt, Tickeal()); 
> 
See Also 
bios, time, TOS 


time—Time function (libe.a/time) 
Get current time 
#include <timeb.h> 
time_¢ time(ép) time_t 


te 


Mark Williams C 453 


time Lexicon 


time reads the current system time. It is a simpler version of the Functipy 
ftime, zp is a pointer of the type time_t, which is defined in the header 
time.h as being equivalent to a Jong. Note that Mark Williams C defines 
current system time as being the number of seconds since January 1, 1979 
OhOOm00s GMT. 3 


Example 
For an example of this function, see the entry for asctime. 


See Also 
time (overview) 


time—Overview: 

Mark Williams C includes a number of routines that allow the user to set 
manipulate time, as recorded on the system’s clock, into a variety of form 
These routines should be adequate for nearly any task a programmer has t 
involves temporal calculations or the maintenance of deta gathered over a long. 
period of time. 


All functions, global variables, and manifest constants used in connection with 
time are defined and described in the header file time.h. 


The ANSI Draft Time Standard 
‘The draft ANSI standard for the C language describes functions designed 10 b 
used with calendar time (i.e., the Gregorian calendar), local time, and dayli 
savings time. 


The basic unit of time is defined as the CLK_TCK, which is defined as om 
tick of the system clock. On the Atari ST, the CLK_TCK is equivalent to 
‘milliseconds. Three types are declared: 


clock _t 
“This is an implementation-specific type that is capable of encoding clo 
time. On the Atari ST, this is set to an unsigned long. 
time_t 
‘This is an implementation-specific type that can represent time. 
Mark Williams C, time_t is defined as a 32-bit number that holds. 
number of seconds since January 1, 1970, OhOOm00s GMT. 
struct tm or tm_t 
This structure encodes the elements of calendar time. It is defined @ 
follows: 
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typedef struct tn ¢ 


int tm sess 1 second (0-591 7 
int tmpin; 7 minute 10-59) */ 

int tm hours 7 hour [0-25}: 0 = midnight #7 

int tmpeay; 7 day of the month [1-28,29,30,31] */ 
int 4 month (0-111: Oedenuery */ 


int 


7 year sinee 1900 4.0. */ 
1 Soy of week (0°62: Sunday */ 
77 day of the year (0-365,368] */ 


int tm isdst; 77 daylight savings tine flag */ 
> ms 

‘The ANSI standard also describes a number of time functions, as follows: 
asctime convert time to ASCIT string 
clock return time since system was turned on 
ctime output an ASCII string that gives the time 
difftime compute difference between calendar times 
gmtime return Greenwich Mean Time 
localtime retura local time 
stime set time (UNIX/COHERENT-compatible) 


Extensions to the ANSI Standard 

‘Mark Williams C includes a number of extensions to the ANSI stendard, These 
are designed to increase the scope and accuracy of the standard, and to ease cal- 
culation of some time elements. 


To begin, Mark Williams C includes three variables that are used by the func- 
tion localtime; it parses the environmental variable TIMEZONE into the 


following: 
timozone seconds from GMT to give local time 
dstadjust seconds to local standard, if any 
name array with names of standard and daylight times 


‘The following functions return information about the calendar: 


isleapyear is this year AD a leap year? 
dayspermonth how many days in this historical month? 


Time on Mark Williams C is modelled efter time on the COHERENT operating 
system, AS noted above, the variable time _t is defined as the number of 
seconds since January 1, 1970, OhOOm00s GMT; this moment, in turn, is ren- 
dered as day 2,440,587.5 on the Julian calendar, This allows accurate calcula- 
tion of time as far back as January 1, 4713 B.C. 


Conversion to the Gregorian calendar is set to October 1582, when it was first 
adopted in Rome. The issue of conversion of when a nation changed from the 
Julian to the Gregorian calendar is moot in the United States, Canada (except 
Quebec), Asia, Africa, Australia, and the Middle Eas; however, users in 
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Quebse, Latin America, Europe, the Soviet Union, and European-influe: 
areas of Asia (e.g., India) may wish to to write their own functions to convert 
historical data properly from the Julian to the Gregorian calendar. 

The following functions assist in conversion from Julian to Gregorian time: 


ime_to_jay convert time_t to the Julian date 
Jday_to_time convert Julian date to time_t 
tm_fo_Jday convert tm_¢ structure to Julian date 
Jday_fo_tm convert Juiian date to tm_t structure 


Atari ST Time Functions 
The Atari ST's ROM BIOS contains a number of functions that manipulate sys— 
tem time. This task is complicated by the fact that the ST has several clocks, 
which do not reference each other; each can be set independently, and each i 
used under different circumstances. 

The following functions convert between standard time and TOS time: 


tm_to_tetd convert tm_t to TOS time 
tetd_to_tm convert TOS time to tm_t 


‘The intelligent keyboard (IKBD) keeps time to the second, but it not suppor 
by either the xbios or the gemdos functions. The following two functions con- 
vert between time as encoded in tm_t and the IK BD clock: 

Kgettime turn IKBD time to tm_t 

Ksettime turn tm_t to IKBD time 


Finally, the Atari gemdos and xbios routines include a number of functions that 
directly manipulate system time, as follows; 


Féatime get/set a file's time and date stamp 
Geitime fet the system time (xbios) 
Settime set the system time (xbios) 
Tgettime get the system time (gemdos) 
Teetdate get the system date (gemdos) 
Tsettime get the system time (gemdos) 
Tsetdate set the system date (gemdos) 

Example 


For an examle of time functions, see the entry for asctime, The following 2 
ample demonstrates the header file time.h, and the functions Gettime, Kget 
time, Ksettime, Settime, stime, tetd_to_tm, Tgetdate, Tgettime, time, 
time_to_tm, tm_to_tetd,tm_to_time, Tsefdate, and Tsettime, 
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include <tine.h> 
amt getdate(p) 
ar “BE 


static tt ty 


sscanf(p, "thciaiadiadi2d. 2d", Et.tm year, &t.tmmon, £t.tm_ndey, 
Et.tmhour, at.tn min, £t.tmsec): 
etm year “= 1900) 
tetmpday -= 1; 
return Bt; 
2 


dodisplayctp, ene 
tt “tp char *nene: 


« 
printf mmennzewm2enord2d. 202d e\n', 
tp->tm_year+1900, tp->tamont!, ‘tp->tm_nday, 
tpeotm hour, tp-stmnin, tp->tm_sec, nana); 
Fy 


‘define display(x) dostsplay(ctm e *)¢x), "91 


raincarge, arsv) 
Int argc; char *eravO); 


« 
if Gorge > 1) ¢ 
tp = getdatecargvt3); 
td = tm.to_tetd(ep); 
t= tn fe tinectp): 
stile) 
Ksettine( py; 
Sevtinecsd); 
Teetdate(td.g dete); 
Teettine(te.g date); 
> 
disalayCtine_to_tmctimecOL>)); 
display(xaettims()); 
displayCtetd to tn¢cettinet))): 
displayctetd_to_tm¢ (Long) Taetdate(rec16»| (unsigned) Tget tinec 2): 
5 
See Also 
Lexicon 
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time.h—Header file 


timezone—Time library data 


TIMEZONE—Environmental parameter 
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|_jday—Time function (libe.a/time_t»_jday) 
‘Convert system time to Julian date 
#include <time.h> 
Jday_t time_to_jday(cime) ti 


time_to_jday converts system time to Julian days. time is the current system 
time. It is declared to be of type time_t, which is defined in the header file 

ime.h 25 being equivalent to a long. Mark Williams C defines the current sys~ 
tem time as being the number of seconds from January 1, 1970, 0hOOm@0S 
GMT. The function time returns the current system time in this format. 


time_to_jday returns the structure jday_t, which is defined in the header file 
time;h. jday_t consists of two unsigned fats. The first gives the number of the. 
Julian day, which is the number of days since the beginning of the Julian 
calendar (January 1, 4713 B.C.). The second gives the number of seconds since. 
midnight of the given Julian day. 


See Also 
jHay_to_time, jday_to_tm, time, time.h, tm_to_jday 


e_t times 


Header file with time-description structure 
include <time.h> 


time.h is a header file that contains descriptions and declarations for elements 
used to manipulate time under TOS. 


See Also 
time, timeb.h 


timezone helps to convert TOS time to a form readable by humans, Tt is an ex=_ 
ternal variable that contains the number of seconds to be subtracted from GMT 
to obtain local standard time. 


Example 

For an example of how to use this routine, see the entry for time 
See Also 

settz, time, TIMEZONE 


‘Time zone environmental parameter 
TIMEZONE=standard:of (sell:daylight: date:date:hour;minutes) 


TIMEZONE is an environmental parameter that is set to information about the | 
user’s time zone. This information is used by etime to construct its description 
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of the current time and day. To set the TIMEZONE paramoter, use the set 
command, as follows: 


setenv TIMEZONE (deseripticnt 


where [description describes your time zone. Most users write this commend 
into the file profile, so that the TIMEZONE parameter is set automatically 
whenever they reboot their system, 


A TIMEZONE description contains at Teast two fields that are separated by 
colons; the first gives the name of the standard time zone and second its offset 
from Greenwich Mean Time in minutes. Offsets are positive for time zones 
‘west of Greenwich and negative for time zones east of Greenwich, 


Fields 3 through 7 are optional, Field 3 gives the name of the local daylight 
saving time zone. The absence of this field indicates that no daylight saving 
time correction should be made. If TIMEZONE contains no additional fields, 
the changes between standard time and daylight saving time occur at the times 
currently legislated in the United States: at 2 A.M, standard time on the last 
Sunday in April, and at 2 A.M. daylight saving time on the last Sunday in 
Gctober. 


Fields 4 and 5 specify the dates on which daylight saving time begins and ends, 
Each consists of three numbers separated by periods. The first number 
specifies which occurrence of the weekday in the month marks the change, 
counting positive occurrences from the beginning of the month and negative 
occurrences from the the end of the month, The second number specifies a day 
of the week, numbering Sunday as one, The third number specifies a month of 
the year, numbering January as one. 


Finally, fields 6 and 7 specify the hour of the day’at which daylight saving time 
begins and ends, and the number of minutes of adjustment. 


Example 
The following are possible descriptions of Central Standard Time: 


The first setting provides conversions to standard time only, a convention used 
by many farmers, The last three settings provide conversions to daylight time 
and specify the default conversion rules in increasing detail. 


Note that under the microshell msh, it usually not necessary to set the offset 
field, unless you wish to keep your system set to Greenwich Mean Time. 


For an example of this variable’s use in a program, see the entry for asctime. 
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tm_to, jday-Time function Hibe-a/tm_to_ fay) 


tm_to_tetd—Time function (libe.a/tm_to_tetd) 
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See Also 
environment, seteny, time 


Notes 
The time zone that time and {time depends on how the time zone was originally 
set. If date and TIMEZONE has the correct offset from Greenwich, then the 
system time is GMT; however, if the time was set on the GEM desktop, or if 
TIMEZONE has set the offset from Greenwich incorrectly, then the system 
time is not GMT, 


The default profile included with your copy of Mark Williams C has a 
TIMEZONE setting for Central Standard Time (CST/CDT), Users who live 
outside that time zone may wish to edit TIMEZONE to reflect their time zone. 


nvert calendar format to Julian tine 
#include <time.h> 
jday_t tm_to_jday(time) tm_t *times 


tm_to_jday converts the system time, as described in the system calendar f¢ 
mat, tO Julian time. time points to @ copy of the structure tm_t, which is 
defined in the header file time.h. The functions gmtime and localtime returns 
the current time in this format, For more information on tm_t, see the Lexicon 
entry for time, 


tm_to_jday returns the structure jday_t, which is defined in the header file 
time.h- jday_t consists of two unsigned ints, The first gives the number of the 
Julian day, which is the number of days since the beginning of the Julian 
calendar (January 1, 4713 B.C.). The second gives the number of seconds since 
midnight of the given Julian day. 


See Also 
jday_to_time, jday_to_tm, time, time.h, time_to_jday 


‘Convert system calendar format fo IKBD time 
#include <time.h> 
fetd_( tm_to_tetd(dime) tm_t 


tm_to_tetd converts the system calendar structure, as returned by the functions 
gmtime and localtime, into a form that can be used by the Atari function Set 
time to set the intelligent keyboard’s clock. 

time points to a copy of the structure tm_t, which is defined in the header file 
time.h, For more information on this structure, see the entry for time. 


tm_to_tetd returns a data element of the type tetd_t, which is defined in the — 
header Tile time.h as being equivalent to an unsigned long. It holds the 32-bit 
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map used by Settime to set the intelligent keyboard's clock. For information on 
‘what the bits of this map signify, see the entry for Settime. 

See Also 

tetd_to_tm, time, time,h 


‘TMPDIR—Environmental parameter 
‘TMPDIR directive names the directory into which msh and its commands w: 
their temporary files. 


It is set with the seteny command, 


See Also 
msh, seteny 


tmpnam—General function (libe,a/tmpnam) 
Generate a unique name for a temporary file 

+#include <stdio.h> 

char *tmpnam(name) char *name; 


tmpnam constructs a unique temporary name that can be used with your 
program. name is the name of 2 buffer into which tmpnam writes the tem- 
porary name. If name is NULL, tmpnam writes the name into an internal buff- 
er that is overwritten each time it is called, 


tmpnam assumes that the temporary file will be written into directory \tmp and 
builds the name accordingly. It returns the address of the internal buffer. 


See Also 
mktemp, tempnam 


i—ctype macro (ctype.h) 
Convert characters to ASCIL 
#include <ctype.h> 
toascii(c) int ¢; 


toascii takes any integer value c and keeps the low seven bits, If ¢ is already a 
valid ASCU character, it is unchanged, 


See Also 
ctype 


tolower—ctype macro (ctype.h) 
Convert characters to lower case 
tolower(c) into; 
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_tolower—ctype macro (ctype.h) 3 


tos—Command 


tolower converts the letter c to lower case. If c is not a letter, the result is un~ 
defined. 


Example 
‘The following demonstrates tolower. 


For an example of its use ina TOS application, see the entry for Fgetdta. 


include <ctype.h> 
Winelude <etdia. hy 
rain 

FILE *fp; 

int ch; 

int filename 201; 

printf(venter rane of file to use: " 

getecfilensne); 

14 (Cfp = fopenfitename,r#)) 1 MOLLY 

while ((eh = fgetcc tp) t= EOF) 
puteharisupper(en) 7 telovertch) + &h); 


5) 
else printf(HCannot open Xs.\nt, tH lename): 

> 

See Also 

clype, foupper 


Convert letter to lower case 
#include <ctype.h> 
_tolower(c) 
Tat 

tolower is a macro that returns c converted to lower case. If c is nota letter, 
the result is undefined. 


See Also 
slype 


Execute GEM-DOS program 
tos program options 


fos allows you to run under msh a program that uses unredirected GEM-I 
file handles, It resets file handle 2 to the aux: devi cousin, the g¢ 
command, fos doss not enable the mouse cursor. program is the name of t 
program you wish to execute; note that you should give the full path name 
the program and its full name, including suffix. options are a list of optio 
that are passed directly to the program to be executed. 
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See Also 
commands, gem 


TOS—Overview 
TOS is the opersting system for the ATARI ST. It includes a number of com- 
ponents, including Digital Research's Graphics Environment Manager (GEM) 
and the GEM-DOS disk operating system. 
The following entries in the Lexicon describe features of TOS: 


AES This describes the GEM Application Environment System (AES), 
which allows the programmer to use predefined windows, icons, pull 
down menus, and other GEM elements. It also lists and briefly 
describes all of the AES routines; each AES routine has its own entry 
within the Lexicon, 


bios This entry describes the TOS function bios, and introduces the 
functions that use it to manipulate the Atari ST's BIOS, 

desk accessory 
This entry describes how to compile a GEM desk accessory, 

error codes 
‘This lists and defines the error codes that can be returned by TOS. 

gemdos This entry describes the TOS function gemdos, and introduces the 
functions that use it to manipulate GEM-DOS, 

keyboard 
‘This describes the layout of the Atari ST keyboard, with the codes 
generates hy each key. 

Line A This describes briefly the Atari “Line A” interface routines, which 
allow the creation and manipulation of graphics displays. 

screen control 
This entry lists the escape sequences used to control text on the Atari 
ST's screen. 

system variables 
This entry lists all of the “magic locations” within memory where TOS 
stores its key elements, 

VDI This describes the GEM Virtual Device Interface (VDI), which gives 
the user access to basic graphics routines. It also lists and describes 


briefly all of the VDI routines; each VDI routine also has its own entry 
within the Lexicon. 
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xbios This entry describes the TOS function xbios, and introduces the fune~ 


tion that use it to manipulate the Atari ST's extended BIOS, 
A number of header files are also used with TOS. These include the following: 


aesbind.h bindings for GEM AES routines 
basepage-h TOS basepage structure 

bios.h declarations for bies functions 

errno.h _gemdos/bios/xbioserror number enumeration 
gemdefs.h miscellaneous declarations 

gemout.h — TOS executable and archive file formats 
linea,h ST linea interface header 

obdefs.h__ miscellaneous object and variable definitions 
osbind.h bindings for bios/gemdos/xbios Functions 


signal.h ST processor exception, extended trap vectors 
stat.h TOS DMABUFFER structure and file attributes 
timesh time and date services 

ydibind.h_ bindings for GEM VDI routines 

xbios.h declarations for xbios functions 


Compiling TOS programs . 
You can include the AES/VDI libraries in your compilations in any of thre 
ways, 
First, you can include the libraries with the library option to the ce command 
line, “To compile the program sample.c, use the following form of the ce co 
mand line: 

ce sample. -ees “Lyd 
The -1 option is described in the Lexicon entry far ec. 
The other two methods involve using a switch on the ce command 
-VGEM is used to create an ordinary GEM program. It automatically links 
the AES and VDI libraries, and calls the special run-time start-up routi 
ertsg.o. For example, to use the -VGEM option to compile sample.c, use 
following command line: 


ce -VOEK sample.e 
ertsg.o has the advantage of being smaller, faster, and simpler than the defaul 
run-time start-up routine, erts0.0, Note, however, that it differs from 
default runtime startup crts0.0 in the following ways: 
1, argy, arge, and enyp are all set 10 zero. 


2. geteny is not enabled; this means programs that use ertsg.o cannot 
environmental parameters. 


Lexicon touch-toupper 


3. stderr will send error messages to the auxiliary porte rather to the console. 


=VGEMACC is used to create 2 GEM desktop accessory. It works in much the 
same way as -VGEM, except that it uses the run-time start-up routine ertsd.o 
instead of ertsg.o, 


The source files for ertsd.o and crisg.o are included with your copy of Mark 
Williams C, should you wish to enhance 


Finally, libaes.a uses the routine erystal.o to call traps. This routine is never 
called by the programmer, but it is automatically linked with libaes, 

See Also 

AES, bios, ertsg.o, gem, gemdos, keyboard, Lexicon, Line A, sereen control, 
VDI, xbios 


touch—Command 
Update modification time of a file 
touch | =e] file ww 
TOS keeps track of when each file was last modified. touch changes the 
modification time of each file to the current time, but does not modify its con- 
tents. By default, touch creates file if it does not already exist; the -c flag sup— 
presses this, 
See Also 
commands, make, msh 


toupper—ctype macro (ctype.h) 
Convert characters ta upper case 
#include <ctype-h> 
toupper(c) Int 
toupper is a macro that converts the letter ¢ to upper case, If c is nota letter or 
is already upper case, the result is undefined. 
Example 
‘This example demonstrates toupper nd putchar. 
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include <etype.hr 
Hinetude <stdio.h> 
main(d¢ 

FILE "fp; 

int Filename (2005 

FovEnter file name: "); 

‘gets( Fi Lename); 
if CCfp = fopentilenane,*e™9) Te MALY C 

wile (ch = foetetfp)} I= EOF) 

putchar(islover(eh) ? toupper(ch) + 


» 
else printf("cannot open X8.\nt, filename): 

y 

See Also 

ctype, tolower 


_toupper—ctype macro (ctype-h) 
Convert letter to upper case 
w#include <ctype.h> 
_toupper(c) 
Tat ¢; 
_ftoupper is @ macro that returns ¢ converted to upper case. If c is not a lett 
the result is undefined. 


See Also 
ctype 


‘Tsetdate—gemdos function 43 (osbind.h) 
Set a new date 
winclude <osbind.h> 
long Tsetdate(i) inti; 


sets a new date. The 16 bits of the integer / encode the dats, 


day (1-31) 
month (1-12) 
5 year (0-119, 0=1980) 


Example 
‘This example demonstrates the macro: Tsetdate and Tsettime, and also uses 
macros Tgetdate and Tgettime. For another example of this function, see 
entry for time. 
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Tsetdate 


finelude <osbind. to 


main) 
unsigned int date; 
unetaned int tine; 
int second 


int hours: 
Sint day; 
int month; 
int yea 


print#(enter the dete end tine (i4/00/71¥7 


Scant *Rd/a/%a %8:3", Bronth, day, Byear, thours, dinates); 


seconds = 0; 


4 (year < 100) 
year +" 1900; 

date = (unsigned) (year-19803<<9) 
| Cunsigredymonthess) 
[eer greciidey; 


time = ((oneignedihours<<t 1) 
[cure igrediratesces) 
[curs ged seconds>>1); 


Limeprintcabout to set the TOS tine tot, tine); 
Sateprint ("About to set the TOS date tom, date); 
Twerdatedate); 

Taettinec tine); 

date = Tyetdatec); /* Get the system date */ 
tine = Tgettine); _/* Get the system tine */ 
timeprint¢*Mow the TOS cine js", time): 
dateprint(Mow the TOS date is", date); 


> 


veld fHadig(buf, onunber, size) 
cher buts 
Int onunber 
ne 


register Long limit; 
register Long number; 
int 9: 


Tye «size ; om 
Linie t= $0; 
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Tsetdate 


if Crumbar >> [infty] |(rember <0) € 
for (9 = 0; a < size; ot) 
tafe eH 
out = 0; 


> 


for (o = 0; 0 < size; oF) ¢ 
Limit 7 1 
butee = ‘Ohanamber/ Limit; 
ramber = mumber Stl 


> 
suf = N08; 
> 


timeprintéstring, tise 
char *ateing 
register unsigned int tine; 
« 


int hours; 
char mine (317 
char ween}; 


weconds = (tine & Ox001F << 1; 
feirutes © (tle >> 5). E OX3F; 
hhoura = (time >> 11) 6 OxtF 


fixdlgtming, sinutes, 29; 
tindigtsecs, secon, 29; 
print {Cte X:Xe:te\n", string, hours, 


> 


doteprintcstring, date) 
char *etrings 
unsigned nt date; 


« 
Int year: 
{nt isonth; 
int dy; 
year = ((date>29) £ Ox7F) + 1980; 
PrintCMs RALA/RA\n, string, month, day, year); 
ey 
See Also 


gemdos, Tgetdate, time, TOS 


468 


‘Tsettime-typede 


‘Fsettime—gemdos function 45 (osbind.h) 
Set a new time 
include <osbind.h> 
long Tsettime(simc) int tine; 


Tsettime sets a new system time, The argument time is an integer whose bits 
encode the time, in the following manner, 


0-4 —_two-second increments (0-29) 
5-10 minutes (0-59) 
11-15 hours (0-23) 


ion, see the entries for time and Tsetdate. 


See Also, 
gemdos, Tgettime, time, TOS 


(ype promotion—Definition 
In arithmetic expressions, Mark Williams C promotes signed types to signed 
types by sign extension and unsigned types to unsigned types by zero padding, 
For example, char promotes to int by sign extension, while unsigned char 
promotes to unsigned int by zero padding, 


See Also 
data formats, declarations 


type checking—Definition 

Every expression has a ype, such a8 int, char, or double. C is not Strongly 
typed, and allows different types to be mixed relatively freely. This gives a 
programmer freedom to write programs of great power and scope, which is 
consistent with the C philosophy of paying out plenty of rope to a programmer, 
Whether she uses that rope to pull herself out of a bog or to hang herself is en- 
tiroly up to her, Mark Williams C checks types mare strictly than the C stan 
dard implies, which most users appreciate. Mark Williams C's type checking 
can be enabled or disabled in degrees, using -VSTRICT and other “variant” 
options with the ec command. 


See Also 
cc 


‘ypedef—Definition 
typedef is a C facility thar allows programmers to define new data types. 
definitions are always made in terms of existing data types; for example, 
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‘typedef long #00; 
establishes a data type called FOO, and defines it to be equivalent to af 
Note that, by convention, programmer-defined data types are written in capit 
letters. 


Judicious use of the typedef facility can make programs easier to maintai 
improve their portability. 
See Also 


declarations, manifest constants, portability, storage class 
The C Programming Language, page 140 


ungete-STDIO function (Tibe-a/ungete) 
Return character to input stream 
#include <stdio.h> 
ungete (c, fp) int c; FILE *fp: 


ungete returns the character ¢ to the stream fp. c can then be read by a subse- 
quent call to gete, gets, getw, scanf, or fread, Exactly one character at a time 
can be pushed back into any stream, A call to fseek will nulli 

previous ungete. 


Example 


Hineluse <stdio.h> 
aint) « 

FILE fpr 

{int ch, lines, neentsr 

Int flenane 2 

lines = nsents = 

printf center nene of file to cneck: "5 

peted i Lenane); 


Mt (Cp = fopen(ti enone," t= MULLY © 
sete tp} I= EOF) « 
\nt) sentiness 
{1 (oh ee 8 | ch ae tt |] ch 
(4 (coh = Foetettpy le 12 ¢ 
4 7 


lee forvehe!.t; (ehetoetette) 


5) 
2 
prinet(Htd Line(a), a sentence(s).\nt, ntlnes, nsents); 
> 
elie printf(Cannot open %é.\n*, f\enste); 
d 


See Also 
fgetc, gete, STDIO 

The C Programming Language, page 156 

Diagnostics 

ungete normally returns ¢; it returns EOF if the character cannot be 
back. 
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union—Definition 

A union describes an area of storage that accepts any one of a number 
heterogeneous data elements. For example, a union may be declared to co 
of an int, « double, and a char *; any one of these three elements can be held f 
the union at a time, and will be handled appropriately by it. 


unions are helpful in deating with heterogeneous data, especially within'st 
tures; however, the programmer is responsible for keeping track of what d 
type the union is holding at any given time. Passing 4 double to a union 4 
then reading the union as though it held an int will y 

dictable, and probably unwelcome. 


Example 

union € 
int ranber: 
double bigrxber: 
char *atr inspite: 

2 uniomine: 

See Also 

struct, structure 

The C Programming Language, page 138 


uniq—Command 
Remove/count repeated lines in a sorted file 
unig |-edul [=n] [+n] [ifiletout filet} 


uniq normally reads input line by line from infile and writes all non-dupli 

lines to oucfile. The input file must be sorted. unig uses the standard input 
output if either infile or outfile is omitted. The following describes the a\ 

able options 


Print each line once, discarding duplicate lines; before each line, print tt 
number of times it appears within the file. 


-d Print only lines that are duplicated within the file; print each tine 
once; do no} print any counts. 


-u Print only lines that are nor duplicated within the file. 


uniq by default behaves as if both -u and -d were specified, so it prints each 
unique line once. 


Optional specifiers allow unig to skip leading portions of the input lines wi 
comparing for uniqueness, 


=n Skip fields of each input line, where a field is any number of non- 
space characters surrounded by any number of white space charas 
(blank or tab). 
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4n Skip m characters in each input line, after skipping fields as above. 


ze Also 
commands 


UNIX routines—Overview 
Mark Williams C includes a number of routines that were originally written for 
the UNIX system and related operating systems; these allow Mark Williams C to 
compile programs that were originally written for these systems. 

The routines are as follows: 


close close a file 
creat create/truncate a file 

dup duplicate a file descriptor 

dup? duplicate a file descriptor 

ermo integer returned by error routine 
_exit exit directly from a program 
ineck set read/write position 

open open a file 

read read froma file 

unlink remove a file 

write write toa file 


See Also 
Lexleon 


—UNIX system call (Ilbe.a/untink) 
Remove a file 
snlink(/p) FILE */p; 


unlink removes the directory entry for the given file fp. The name is a histori- 
cal artifact, 


Example : 
This example removes a file named on the command line. 


unset-unsigned 


Inaintarse, sravy int arger char tarqvinz € 
register int 1; 


for 


«argc; +9) ¢ 
Hf Cunlinktaravttt) = 1) € 

printfncannot unl ink \"Re\"\n", argvCiI}; 
exits 


exiteo: 


> 
See Also 
UNIX routines, STDIO 


Diagnosties 
unlink returns -1 if there are any errors, and zero otherwise 


unset—-Command 
Discard a shell variable 
unset VARIABLE 
unset discards a variable that had been set with the set command, 
if you wished to discard the the variable b, simply type 
dewet 
and it will be erased, 
See Also 
commands, msh, set 


unseteny—Command 
Discard an environmental variable 
unseteny VARIABLE 


unset discards an environmental variable. For example, if you wish for 
reason to discard the TMPDIR variable, type 
unseteny THPOIR 


See Also 
commands, msh, seteny 


unsigned—Definition 
The unsigned modifier tells the compiler to treat the variable as anu 
value: This in effect doubles the largest positive value storage in that type, 
changes the lowest storage value to zero. Note that the 68000 uses “two's 
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unsigned 


exicot 


plement” storage, not sign magnitude. 
See Also 
data type 
The € Programming Language, page 34 
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¥_are—VDI function (ibydi.a/y_arc) 
Draw a circular arc 

#include <aesbind,h> 

#include <vdibind.h> 

yoid y_arc(handle, xcoord. yeoord, radius, beginangle. endangle) 
int handle, xcoord. yeoord, radius, beginangle. endangle, 


¥ arc is a VDI routine that draws a circular arc. handle is the virtual devig 
VDI handle. xcvord and ycoord give, respectively, the X and Y coors 

the imaginary center of the circle of which v_are is drawing a sect 

is the radius of the imaginary circle, These measurements will differ, de 
ding on whether the device has been set as using normalized device coordinat 
(NDC) or raster coordinates (RC). Finally, beginangle and endangle git 
respectively, the beginning and end angles of the arc, measured in tenths Of 
degree, Counting on an imaginary clock, zero degrees is at 3 o'clock, 90 
grees (900) at noon, 180 degrees (1800) at 9 o'clock, and 270 degrees (2700) 
o'clock, 

See Also 

TOS, » circle, VOL 


¥_bar—VDI function (Iibydi.a/y_bar) 
Draw a rectangle 
winclude <aesbind.h> 
‘include <vdibind.h> 
void y_bar(handle. xyarray) int handle, xyarraytl; 


y_bar is @ VDI routine that draws a rectangle. Unlike its cousin vr_reel 
yobar can draw a perimeter as well the preset fill pattern, 


handle is the virtual device's VDI pattern. xyarray sets the X and Y coordi 
from which to construct the rectangle; the even-numbered entries indicate 
X coordinates, and the odd-numbered entries the Y coordinates. Which 

of the rectangle each pair of coordinates indicates will differ dependia 

whether the virtual device has been set to normalized device coordinates (ND 
or to raster coordinates (RC). On an NDC device, the first pair points 101 
lower left-hand corner and the second pair to the upper right-hand cori 
whereas on an RC device, the first pair points to the upper left-hand 
and the second pair to the lower right-hand corner. 


Note that to use this routine, the fill type must be set with ysf_interior, the 
style by ysf_style, the perimeter flag by ysf_perimeter, and the fill color 
ysf_colar. To output a complex polygon (ie. shape other than a recta 
use the routine y_fillarea 
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‘The following program draws a filled rectangle onto the screen, By clicking the 
mouse’s left Button and dragging the mouse, you can draw a rectangle on the 
screen, Pressing the “T’ key changes the rectangle’s ‘ype of fill; and pressing the 
‘5' key changes its siv/e. Pressing <retura> exits 


include <gendefe b> 
Hinelude <aesbind.h> 
finelude <ydibines 


define RETURN Oxc00 7 scan code for <returr> bey */ 
Héctine T KEY OK147E (7 sean code for T key */ 
fdetine S_KEY OXIF73 7 scan code for S key */ 


(* global Line A variables used by val; HST be included */ 
(nt tontel 121, IntinCY28), preinct28s, intout 128), pteouect281; 
(t array used by v_bare */ 
int ayarrayt = C4, ty ty 195 
(ff array used by va_clip() */ 
ine etiparraya = 1, 1, 839, 399 95 
orraye used by v_opwt(> */ 
Ine work int) = € 15 1, 1 
Int work out (5725 


/* throwaway declarations, £0 keep system from scribbling over Isself */ 
Int nowhere = 0; 
Rect norect = (0, 0, 0, 0; 


maine) ¢ 
7* declarations used by evnt_multi() */ 
int selection: 17% cose for event that cccurred */ 
Lnslaned int which © (HULKEYSO | Mi SUTTON): 
fine clicks = 1; 7 no. of clicks expected on mouse button */ 
{nt button = 17 7 sich button; 1 = leftmost */ 
jt buttonstate = 1 77 button state expected; 1+ down */ 
fine butferttt 7 place to write AES messages */ 
Int mousex; / pouse X coordinate */ 
int mousey; * neuse ¥ coordinate */ 
unsigned ey: Ney typed by user */ 
(/* mise declarations +) 
int vdihandle: virtual device's handle */ 
int : type of fills 
int : vie of FLL */ 
int Wigth of rusberbor User draws */ 
int Gepth of cubbertox uer draws */ 
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vdinandle = grat 
vopnvuk(work in, Eydinandie, work out): 
vi clip(vdinandie, 1, clipartay); 
vs¥_perineter(vdihardle, 1); 


« 

‘selection = ent multiwhich, clicks, button, buttonstate, 
0, norect, 0, nérect, buffer, 0, 0, kmoutex, Bnouscy, 
Hromere, ‘Incwhere, Ukey, hnownere); 


suitch(selection) ¢ 
case Mi KEvaD: 
Suttenckey? 
cease RETUD 
vel svekcvdihandl ed: 
oppl_exitO; 
ext et0: 


fort, 


cose TE: 
type = (estype85); 
vet_interior(rathandle, type): 
grai_mouse(i OFF, Knowhere); 
y_bartvdinandle, ‘syarray); 
graf ecuse(H OK, Knowhere’ 
break; 


case KEY: 
Style = (ceestyteReenen7 
vst_styletvaihandle, style); 
srai_nouse(MOFF, Enoshere); 
Vbarcwainandie, ‘xyarray); 
graf _mouse(i_Ox, Boowhere’ 
break; 


> 
reeks 


cave BUTT 
aret_ribexcnouser, mousey, 5, 3, Suidth, Sdepth 
yarreyiOh = mouses 
syarrey(0) = sourey: 
syarreyi2) = (wouserswidth 
myacrayia) = (wooeeredept 
ret mouseih OFF, Brower 
Ubarcwsinsndie, ‘yerray 
Sraf_seune(H ON, Sreanere); 
resi 
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¥_bit_image 


2 


See Also 
TOS, vr_reefl, VDI 


¥_ bit_image—VDI function (libydl.a/v_bit_image) 
Print a bit image file 
winclude <aesbind.h> 
include <vdibind.h> 
yoid ¥_blt_Image(handle. filename, aspect, scaling. points, xyarray) 
int haidle, aspect, scaling. points, xyarray{a}; char * filename: 


»_bit_Image is a VDI routine that prints bit image file. handle is the virtual 
device's VDI handle. filename points to the name of the file that holds the bit 
image; note that this name must be terminated with a NUL character. 


aspect gives the code for the aspect ratio used to transfer the bit image onto 
paper, as follows: zero indicates that aspect ratio should be ignored; one, honor 
pixel aspect ratio; and two, honor page aspect ratio. Pixel aspect ratio ensures 
that the figures within the bit image remain constant, eg., that a circle will 
remain circular; this may involve some cropping or shrinking of the image when 
printing, Page aspect ratio ensures that one full page in the bit image file is al- 
‘ways printed as one full page of paper; this may result in some distortion of the 
figures within the bit image, however. 


cpling describes how the bit image should be scaled onio to the page being 
printed; zero indicates that the X and Y coordinates should be scaled together, 
Whereas one indicates that they should be scaled separately. Note that this ar 
gument is meaningful only if the variables in xyarray are set, If the X and Y 
Coordinates are scaled together, the printed image may not fully occupy the rec 
tangle defined by xyarray on the output device. If they are scaled separately, 
the bit image will entirely fill the area defined by xyarray, but the setting of 
aspect will be ignored, 


Finally, xyarray defines the upper left-hand and lower right-hand corners of 
the area on the page into which the bit image will be printed. 


See Also 

TOS, VDI 

Noies 

Thig routine uses the VDI's GDOS in its operation, It should not be used if the 
GDOS is not present in your edition of VDI. 


Mark Williams C 


ellarray-y_cirele 


¥_cirele-V DI function (libydi.a/y_cirele) 
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VDI function (libvdi.a/v_cellarray) 
Draw a table of colored cells 

#include <aesbind.h> 

include <vdibind.h> 

void v_cellarray(handfe. xyarray, rowlengih, cells, rows, mode. eellarray) 
int handle, xyarray, rowlengthl4], cells, rows, mode, cellarrastnh; 


y_eellarray isa VDI routine that draws a table of ¢olored cells, handle is t 
virtual device's VDI handle. xyarray gives the X and Y coordinates for th 
rectangle in which the table will be drawn, Note that these values will vs 
depending on whether the device is set to normalized device coordinates (1 

of raster coordinates (RC), On NDC devices, xyarray/0) and xyarray{ I] giv 
respectively, the X and ¥ coordinates of the lower left-hand corner of the ree 
tangle, whereas xyarray/ 2] and xyarray[ 3] give the coordinates for the upp 


rowlength gives the horizontal length of the table to be shown, in NDCs or 
cells is the number of cells to be drawn in each row, and rows is the number 
rows of cells to draw. mode is the writing mode in which the cells will B 
drawn: one indicates replace mode; two, transparent mode; three, XOR 
(exclusive or); and four, reverse transparent mode. 

Finally, cellarray gives the array of colors to be shown in the cells. must 
‘equal to cells times rows. 
See Also 

TOS, VDI, vq_cellareay 
Notes 


This routine uses the VDI's GDOS in its operation, It should not be used if th 
GDOS is not present in your edition of VDL 


Draw a circle 
#include <aeshind.h> 
#include <ydibind.h> . 
void y_circle(andle, xcoord. yeoord, radius) int handle, xcoord, yeoord. radius 


y_circle is 4 VDI routine that draws circle. handle is the virtual device's VB 
handle, xcoord and ycoord give, respectively, the X and Y coordinates of tt 
circle's center. radius gives the circle’s radius_ These measurements Wi 
depending on whether the device has been defined as using normalized de\ 
coordinates (NDC) or raster coordinates (RC). 


exicom ¥ circle 


Example 

‘The following program, called circle.c, draws a circle on screen. The first 
mouse click sets the circle’s center; the second mouse click sets its radius. The 
‘W" key cycles through the available write modes, for truly psychedelic effects, 
Pressing <return> exits. Compile it with the command line 


ce -V -VOEM cirelee -Im 
to include the necessary mathematics routine. 


inc\vele <peedete. n> 
include <neabind. b> 
Bineiude <wdibind. he 


fief ASTERISK 3 code far drawing an esterisk marker */ 
doting UP 0 souse tutton i op */ 

sot OWN 1 rouse button is down */ 

detine UXEY OX1177 sean code returned by W key */ 

fsetine RETURN Ox1C00 7% sean code ceturned by <returr> key */ 
fete KOR 3 7 NOR mode for writing mouse pointer */ 


J globol Line A variables used by vai; MIST be included + 
(ne contrt 12}, Incintt28), pesintt283, intovt (128), pesouttt2e); 


1M array used to calculate radius */ 
‘nt wyareaysed; 


/* array used by v.pmarker(> */ 
int eymarker (2); 


(> array used by va_clipl) */ 
ine eliparray(l = €1, 1, 689, 399 95 


(7 arrays used by v_opmk() */ 
int vork tnt = C90 Wty A WUen 
nt work_out 571; 


/* tarow-aeay declarations, to Keep systes fron scribbling over itself */ 
nt nowhere = 0; 
Rect norect = (0, 0, 0, 09; 


rained € 
7* declarations Used by emt_multiCn */ 
Int selection; /* code for event that sccurred */ 
unefgned (nt which = (OU_KEYED | 981 SUTTON); 
nt clicks = 1; 77 no. of clicks expected on mouse button */ 
int button = 1; (7 wich button; 1 = leftmost */ 
int butfer (1); 7 place to write AES messages 
int mousex: @* mouse X coordinate */ 
int mousey 77 nouse ¥ coordinate */ 
unsigned key; [7 key typed by user */ 
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[* mise declarations */ 


int vdihandle; 79 virtual device's handle "7 

int writectr [? weed to cycle through write rodes */ 

int fitletr 7 used to cycle through circle FiLL styles 4 
int n=O; 77 used to keep track of xyarray */ 


here we 90 
oppl_init( 
‘raf mouse(ARACM, nowhere); 

wdihandle = graf haedleZnowtere, tnawhere, Sravhere, Inowhere); 
Yopewwk(work in, Byditindle, workout 

vi_eliptvaihandte, 1, eliparrayy; 


vat_interior(ydihandle, 2); 
Veflperineter(vdinardte, 13; 
vam height(wdihandle, 39; 
vem_typetudthandie, ASTERISK); 


forts:) € 
selection = emt multi(unich, clicks, button, 00, 
0, norect, 0, norect, buffer, 0, 0, imaunex, Rnousey, 
Inowhere, ‘tnowhere, tkey, bnowhere 


awitch(telection) ¢ 
conse MUEEYRO: 

Tt (hey #= RETURN) ¢ 
'elswuk(vdihandt ey; 
oppl_exit(03 
extti0); 


) 
it (key == LXEYD 

wei vectre 
break: 


case Ml BUTTON: 
fevnt_butten(elieks, button, UP, 
Knosbere, Enowhere, Enoshere, Enoshere) 
Hines 00 ¢ 
7 drow center marker in X0R mede */ 
xymarker{0) = mouses; 
xymarker {1} = sousey 
graf mouse(M OFF, kncunere); 
swe _nodeCyaibandle, X08); 
V pmarkee(odibandle, 1, xymarkerd; 
graf mouse(h OM, Anownere); 


y_clear_disp_list 


syarrayines) 

xyartayine+l 

ifin> DC 
neo; 
Filletress 
[7 3OR-auay the center narker ... */ 
\VprarkerCrdinardla, 1, xymarker)s 
7 vos and set new drauing sede */ 
veur_node(dihandle, (writectr¥sye1); 


vot stytecvdihandie, CH LLeER2Oe19; 
deaveircletvdthardle); 


> 
drayetretechandle) 


fot handle; 
< 
int eat; /* Firat Leg of triangle to compute radius */ 
int eg2; secord Leg */ 
int radius /* radius of circle * hypotenuse */ 
‘extern double hyper); 7* declare hypot) function #/ 
ta 
+ calculate two Legs of Fight Erfangie, then use Pythagorean theoren 


* to compute hypotenuse, which equals rediue of circle to be dravn, 
+ Note necessary caste of variables. 
” 


Legh = abstayerray (2) ~ xyarray(00); 
Leg2 = abs(ayarray(3) ~ xyarray1); 
radius = (int) hypot( (double) Lest, (double) Leg2r; 


7* now, draw the circle */ 

‘graf_mouse(H_oFF, Knowhere); 

velfclethandle, xyarray(0l, xyarrayit}, radius); 
| mouse(H Ok, Roowbere); 


See Also 
TOS, v_ellipse, VDI 


)_clear_disp_list—VDI function (Iibydi.a/y_clear_disp_list) 
Clear a printer's display list 
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y_elewk-y_elsywk Lexi 


void y_clear_disp_list(handle) int handles 


¥_clear_disp_list is a VDI routine that clear’s a printer's display list. Until 
the related Function _elrwk, it does not set a new page. 


See Also 
TOS, v_form_adv, y_clrwk, VDI 


Notes 
‘This routine uses the VDI's GDOS in its operation. It should not be used if 
GDOS is not present in your edition of VDI. 


¥_clewk—-VDI function (litydi.a/y_elrwk) 
Clear the virtual workstation 
#include <aesbind.h> 
include <ydibind-h> 
void »_elewk(handle) tat handles 


+_clrwk is a VDI routine that clears the virtual workstation 
automatically after a device is opened. It clears the screen device by setting, 
to the background color, and clears a hard-copy device (e.g... printer, plotte 
by sending a new-page signal, handle is the device's VDI handle. 


Example 
For an example of this function, see the entry for v_gtext. 


See Also 
TOS, v_clear_disp_list,y_form_ady, VDI 


¥_ elsywk—VDI function (libydi.a/y_ctsywh) 
Close the screen virtual device 
#include <aesbind.h> 
#include <ydibind.h> 
void v_elevwk(handle) int handle: 


¥_elsywk is @ VDI routine that closes the screen virtual device, It also fl 

all appropriate buffers, frees the space assigned to the screen's device dri 
and otherwise performs other tasks to ensure thal the device is cl 
gracefully. handle is the screen's VDI handle. 


Example 
For an example of this routine, see the entry for y_pline. 


484 Mark Willia! 


v_elswk-v_contourfill 


See Also 
TOS, VDI, y_clswk, y_oparwk, 


y_clswk—VDI function (libydl.a/v_clswk) 
"Close a virtual workstation 
include <aesbind,h> 
#include <ydibind.h> 
void y_clswk(handle) Int handle; 


+_elswk is 8 VDI routine that closes s virtual workstation. It also flushes the 
any associated buffers and frees the memory allocated to the workstation’s 
driver, to conclude matters gracefully. handle is the device's VDT handle. 


See Also 
TOS, VDI, ¥_opnywk, ¥_opnwk 


Notes 

This routine uses the VDI's GDOS in its operation. It should not be used if the 
GDOS ig not present in your edition of VDI. To close the screen device, use the 
related Function v_elsvwk. 


)_contousfill—VDI function (libydi.a/y_contourfill) 
Fill an outlined area 
#include <aesbind.h> 
include <vdibind.h> 
void y_contourfill(handle, xcoord, ycoord, color) 
Int handle, xcoord, ycoord, color; 


y_contourfill is a VDI routine that fills an outlined area with a fill pattern. 
Note that the fill type must be set by the function ysf_tuterlor, and the fill 
style by the function vsf_style. 


handle is the virtual device's VDI handle, xcoord and ycoord give, respectively, 
the X and Y coordinates of the point at which filling is to begin, Finally, color 
is the code for the color at which filling stops. For a table of color settings, see 
the entry for ¥_opawk. 


Example 

The following example lets the user draw a number of “rubber lines" on the 
soreen, The ‘W' key floods an enclosed area with the fill pattern. Pressing 
<return> exits 


Finclude <oendefe.t> 
Hinelude <eesbind.t> 
Wineluse <vaibind.t> 


y_contourfill 
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‘Het ine RETURN oxte00 (Jt scan code returned by return key */ 
‘etine VKEY Ox1177 77 sean code returned by W key */ 

‘iefine UP 0 7 wouse button is wo */ 

Satine DOM 1 (72 mouse button is dawn */ 

fisefine CLICKS } 7* no. of clicks expected on mouse button */ 
fete BUTTON 1 72 shich button; 1 = leftnost *7 

‘define YOR 3 7 make weiting sode HOR */ 

fetine REPLACE 1 / wake writing mode REPLATE */ 

define FULT & 79 set FILL type to little Mults® *7 

‘set ine BLACK 1 7° code for color black */ 


7* global Line A variables used by vdi; MIST be included */ 


nt contri (123, Inein(T26), ptsin(Y281, intouttt28), ptsour (28); 


rs 


* array used by va_clip(): RUST be set, of images that extend 
' beyond the screen perimeters will write over Low-Level memory 


+ ee 
” 


RAM disks, spooters, etc.) 


nt eliparraytt = C1, 1, 639, 399 9; 


(* array used by evnt_multiCn, for writing AES messages */ 
lint butter ct} 


/* arrays used by v_opwac) */ 
nt workin) = €1, 1 ty 


(int work out (572; 
1* array uted by v_ptinec) */ 


Int xyarray 


/* throw-auay declaretions, £0 keep syste fram scribing over (taelf */ 
{nt nowhere = 0; 
fect norect = C0, 0, 0, 0 9; 


ning) 


« 


J* declarations used by evnt ulti) */ 


int selection 
uewigned keys 


int mousey: 
tht vaiherele; 
int flag = 9; 


here we goo. */ 
eppl_init; 
graf_nouse(ARIOM, Encuhere); 


vdlhandle = graf’handle<tnomere, Unawhere, Enowhere, Enowhere); 


voprvuk(work_in, Evdihandle, work out); 


code for event that occurred */ 
scan code of key pressed by user */ 
mouse X coordinate */ 

mouse ¥ coordinate */ 

virtual device's handle */ 

thas Line been drawn yet? */ 
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esicon y_contourfill, 


va_eliptvdinendie, 1, etiparrey) 
vef_interier(vdihendie, FI); 
vavt_pede(ydinandle, X08); 


fort 


Xa 
Selection = ewnt_multfOU_KEYSD | BUTTON, CLICKS, BUTTON, 
DOM, 0, norect, 0, norect, buffer, 0, 0, knousex, 
Incusey, tneshere, nowhere, Bkey, nowhere); 
switencselection) © 
‘cane M_KEYED: 
FF (key == RETURN) ¢ 
‘vclsvak¢vdihandted; 
appl_exit¢ 
ext); 


> 


ft (key == WEY) ¢ 
rat_souse(H OFF, Groxtere): 
vcontourfil(vdinandie, ‘ouses, mousey, BLACK; 
graf roused OW, Knowhere); 

‘J 

beonks 


ease WU sUTTOU: 
7 rubber ine! routine */ 
$f (flog > 0) € 
7 Af Line has moved «=. */ 
Hf Ceayarray(2) I= sounex) || Cayarrayt3} 1= mousey)) ¢ 


1 ese undeaw old Une... */ 
grat mouse(M OFF, nowhere); 

W plinetvdinandle, 2, xyarray): 
grat mouse(H_ok, dnouhere 

(Ut sss change tar endpoint... #7 
xyatreyi2] = pousex: 

yacray(3] = mousey: 


ard draw new tine */ 
f mouse(M OFF, Knowhere! 
et vaihandl 


2 
voi 
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y_curdown Lexi 


v_curdown—VDI function (libvdi 


ABB 


if (flag == 0) 
(72 redraw (ine in REPLACE mode */ 
‘ewe mode (wdihandle, REPLACE); 
graf_mouse(W OFF, Bnowhere); 
vplinetvdinardle, 2, xyarray); 
graf_mouse(K 4, Enowtere); 
‘vswr_mede(vdihondie, x08); 


[7 reset endpoints */ 
yarray(o) = musen; 
nyarray()] = mousey; 
syacray(2]) = mouse; 
xyarray(3] = mousey; 
flag = tz 


3 
hag = check(? 


check() 
int buttenstate = 17 7* button state */ 
fevnt multi CM) TIKER, CLICKS, BUTTON, 


UP, 0, norect, 0, rorect, buffer, 0, 0, nowhere, 
nowhere, Bbuttonstate, Enowere, Enowhere, browhe 


returntbuttonstated; 

> 

See Also 

TOS, VDI 

Notes 

Due to the way the AES routine reads the mouse buttons, the example 
always notice that the mouse button has returned to the up position, 


/y_curdown) 
Move text cursor down one row 

include <aeshind.h> 

winclude <vdibind.h> 

void _curdown(hand/e) int handle; 


¥_curdown is @ VDI routine that moves the text cursor down one row. Tt 
not affect the cursor’s horizontal position. Note that the virtual device 
first be put into text mode with the function y_enter_cur before this f 
can be used. handle is the virtual device's VDI handle. 
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¥_curhome-+_eurright 


Also 
TOS, + curhome, _curleft, y_curright, y_curup, VDI 


+_curhome—VDI function (Iibydi.a/y_eurhome) 
Move text cursor to the home position 
s#include <aesbind.h> 
Finclude <vdibind.h> 
void y_curhome(handle) int handle; 
y_curhome is a VDI routine that moves the text cursor to the home position, 
ie. to the upper left-hand corner. Note that the virtual device must first be 
put into text mode with the function y_enter_cur before this function can be 
Used, handle is the virtual device’s VDI handle 


Sev Also 


‘TOS, »_curdown, y_curleft, »_curright, y_curhome, VDT 


¥_curleft—-VDI function (libydi.a/y_curleft) 
Move text cursor left one column 
include <aesbind.h> 
winclude <ydibind.h> 
vold y_eurleft(handle) int handle; 


»_curleft is @ VDI routine that moves the text cursor one column to the left, It 
does not affect the cursor's vertical position. Note that the virtual device must 
first be put into text mode with the function y_enter_cur before this function 
ean be used, handle is the virtual device's VDI handle, 


See Also 
TOS, »_curdown, y_curhome, v_curright, y_curup, VDI 


)_curright—VDI function (libydi.a/y_curright) 
Move text cursor right one column 
#include <aesbind.h> 

lude <vdibind.h> 

old y_curright(iandle) tat handles 


¥_curright is a VDI routine that moves the text cursor one column to th right, 
It does not affect the cursor’s vertical position, Note that the virtual device 
must first be put into text mode with the function y_enter_cur before this 
function can be used. handle is the virtual device’s VDI handle. 
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y_surtext-y_dspear 


¥_eurtext—VDI function (libydi.a, 


¥_curap—VDI function (libval.n/' 


y_dspeur—VDI function (tibydi-x/v_dspeur) 
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See Also 
TOS, y_curdown, ¥_curhome, _curleft, y_curup, VDI 


curtext) 


Write alphabetic text 
#include <aesbind,h> 
#include <vdibind.h> 
void y_curtext(handle, string) int kandle; char *string; 


+_curtext is a VDI routine that writes alphabetic text on the virtual devic 
Note that to use this routine, the virtual device must fitst be placed in te 
mode, using the routine _enter_cur. handle is the virtual device's VDT handl 
siring points to the NUL-terminated string of alphabetic characters to be wri 
ten. 


See Also 
TOS, VDI 


_curup) 
Move text cursor up one row 
#include <aesbind,h> 

Winclude <vdibind.h> 

void _curup(handle) int handle; 


¥_curup is VDI routine that moves the text cursor up one row. It does not 
Feet the cursor's horizontal position, Note that the virtual device must first 
put into text mode with the function y_enter_cur before this function cam] 
used. handle is the virtual device's VDI handle, 


See Also 
TOS, y_curdown,y eurhome, y_curleft, y_curright, VDI 


‘Mave mouse pointer to point dn screen 
‘include <aesbind.h> 

#include <vdibind.h> { 
void y_dspeur(handle, xcoord. ycoord) int handle. xcoord. ycoord: 


y_dspeur is 2 VDI routine that moves the mouse pointer to a specified point 
the screen. handle is the virtual device's VDI handle. xcoord and ycoord: 
respectively, the X and Y coordinates to which the mouse cursor will be mo 


See Also 
TOS, VDI 


¥_eeol-y_¢llare 


_eeol—VDI Function (Iibydi.a/+_eeol) 
— Erase text from cursor to end of screen 
include <aesbind.h> 
include <vdibind.h> 
void v_eeol(handle) int handle; 


¥_eeol is a VDI routine that erases alphabetic text from the position of the text 
cursor to the end of the line. Note that the virtual device must first be put into 
text mode with the function v_enter_cur before this function can be used. 
handle is the virtual device’s VDI handi 


See Also 
‘TOS, y_ecos, VDI 


+_ee0s—VDI function (libydi.n/y_eeos) 
Erase from text cursor to end of screen 
#include <aesbind.h> 
#include <ydtbind.h> 
void y_eeos(hand/e) Int handle; 


¥_ecos is a VDI routine that erases a virtual device from the position of the text 
cursor to the end, Note that the virtual device must first be put into text mode, 
with the function y_enter_cur before this function can be used, handle is the 
virtual device's VDI handle. 


See Also 
TOS, +_eeol, VDI 


\_ellare—VDI function (libydi.a/v_ellare) 
Draw an elliptical are 
include <aesbind.h> 
#include <ydibind. b> 
old v_ellare(handle, xcoord. ycoord. xradius. yradius, keginangle, endangle) 
int handle, xcoord, ycoord, xradius, yradius, beginangle, endangle; 


y_ellare is a VDI routine that draws an elliptical arc. handle is the virtual 
device's VDI handle. xcoord and yeoord give, respectively, the X and Y coor- 
dinates of the center of the imaginary ellipse of the curve being drawn is part, 
xradius is the horizontal radius of the ellipse, and yradius is the vertical radius. 
Note that all of these values will vary, depending on whether the virtual device 
‘uses normalized device coordinates (NDC) or raster coordinates (RC). Finally, 
beginangle and endangle represent the beginning and end angles of the ellipse, 
in tenths of a degree. On an imaginary clock, zero degrees is at 3 o'clock, 90 
degrees at noon, 180 degrees at 9 o'clock, and 270 degrees at 6 o'clock. 
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y_ellare 


Example . 
The following program uses STDIO routines to create a “rough-and- 
dialogue; the user sets the X radius, the Y radius, the beginning angle, andi 
end angle, which are then used to draw an elliptical arc on the screen. 


Finelude <gendefs.t> 
include <aesbind.h> 
Fineluse <edibindh> 


#éefine ESCAPE Ont [7 seen code returned by escape key */ 
et inm ROUNDED 2 /* put rounded ence on Lines */ 

tset ine REPLACE 1 (7 cade for REPLACE writing mode */ 
Wet ine KOR 3 79 cade For XOR writing mode */ 


17 globol tine A variables used by vii; WIST be included */ 
Int contrl (12), (ntin(1281, ptsint128), intout {128}, ptsout (1283; 
” 

array Used by vé_etip(); MIST be set, or inages that extend 

‘+ beyond the screen perimeters will write over low: (evel menory 
+ RAK disks, apooters. etc.? 


int cliporrayQ) = (1, 1, 689, 397 9: 


1% arrays used by drawl inet) */ 
ryvert(l = € 320, 1, 320, 399 95 
wyhori2t = (1, 200, 639, 200 3; 


(arrays used by vopwik() */ 
Int work tnt) © C1) %y Ve My Te 
int work-out (573: 


WW 2% 


/* throw auey dectaration, to keep systen from scribbling over Itaelt */ 
nt novhere = 0; 
maine © 
unsigned keys ey returned by user */ 
ine vdihandle; Virtual device's handle */ 
int radius; length of X radius */ 
int yredius; Length of ¥ radius */ 
nt beginangte: beginning enate */ 
int endangle: end sngle */ 
77 OK, here we go +. */ 
appl_initQz 


Voprvak(work_in, Avdihandle, work cut); 
va cliptudinasdle, 1, eliparrsy); 
val_endstwdinandle, ROUNDED, ROUNOED); 


exicon v_ellare 


fercnd © 
[printfe*Type <raturne to continue, <ese> to axit.\n"); 
key = emnt_keytd; 
ssuttehc(chardkey) € 
cee ESCAPE: 
v_clsvak¢vdihendled; 
appl_exito: 
exit 
cease "nt: 
drawl ines(vdihandle); 
/* enter X radios */ 
kradius = getdate(*Enter X radius (screen, 0:320)H); 
nyhortr(0) = 320 - aredive; 
nyhoriz(2) = 320 + xradius; 
‘rest ines(vaiharde) 


/* enter ¥ radius */ 
yradius = getdota(vénter Y radius (screen, 0-200)"); 
kyvere tt) = 200. yradiues 
yert(3) = 200 + yradivs 
rout ines (vdihardie): 

/* Enter beginning angle */ 
beginangle = getdstacénter beginning angle (0-360)") * 10; 
deal ines(vdihardle); 

77 Enter ond angle */ 


erengle = getdats(*Enter end angle (0°360)") * 10; 
ddeaul inweudihanded; 


[7 tod now, drow the elliptical are */ 
val victh(vdihandle, 595 
vellerccvdihandie, 320, 200, xradius, yradius, 
beginangle, endangle); 
bresk: 
default: 
bresky 
2 
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¥_ellipse—VDI function (libvdi.a/y_ellipse) 


494 


rout inescnenatey 

nt handle: 

c 
print CS3E\n" 
vsl_width¢handle, 13 
v.plinethandle, 2, xyvert); 
viplinethandle, 2, xyhoriz 


5) 


getdatatmessage) 
char *message: 
« 


forts2) ¢ 
‘char strlngt200; 77 steing ured with wer input */ 
int valve: 7° value user Intended */ 


printfa: *, message); 
fflushestdout): 
it((unlve = atol (gets(string) 9 >= 0) 
returntvatue); 
> 
Fy 


See Also 
‘TOS, VDI, v_ellipse 


Draw an ellipse 

finclude <aesbind.h> 
ainclude <vdibind.h> 
void y_ellipse(handle, xcoord, yeoord, xradius. yradius) 
int havidle, xeoord, yeoord, xradius, yradius; 


y ellipse is @ VDI routine that draws an ellipse. Aandle is the virtual devi 
VDI handle. xcoord and ycoord give, respectively, the X coordinates and 3 
coordinates of the ellipse’s center. Note that these measurements will chan 
depending on whether the virtual device is set to normalized device coordinat 
(NDC) or raster coordinates (RC). Finally, xradius gives the ellipse's horizon 
radius, and yradius gives its vertical radius. 


Example 
‘The following example draws ellipses on the screen. Clicking the mouse d 
a rubber box; releasing the mouse fixes the box, whose dimensions are u 

calculate the’ellipse. Pressing the ‘W" key cycles through the available 

modes, for truly psychedelic effects. Pressing <retura> exits 


y_ellipse 


Ainelucte <pomdets.bo 
Jinelude <aesbind.to 
include <vdibind b> 


séctine DOW 1 [mouse button is down */ 
foetine WREY Ox1177 ‘7 seen code returned by 4 key */ 
fiefine RETURN OxTC00 [scan code returned by <returm tay */ 


> elobol Line A variables Used by val; MUST be included */ 
fon contrl (123, ineincl2B), pesin(t28), Intout 1281, pesout (128); 


/* array used by vs_elipO) */ 
int eliparray) = Ct, 1, 639, 3999: 


/* acrays used by v opwkt) */ 
ine workin = C1, 11 1 1 
{int workout (573, 


[7 threw ebay declarations, to keep systen from scribbling over itself */ 
fot nowhere © 


Rect narect = (0, 0, 0, 09; 


maine) © 
/* declarations used by ene multiC) */ 
int select (on; 77 cose for event that cccurred */ 
nwigned ine ablch = (MU_KEYED | Mi BUTTON); 
int eticks = 17 77 ro. of clicks expected on mouse button */ 
int button = 1; 7 sich button; 1 = leftmost */ 
int buffert111; 7? place to weite AES sessagen */ 
7 mouxe X coordinate */ 
7 mowne ¥ coordinate */ 
> key typed by user */ 
(* aise dectarattions * 
int wdihandl Virtual device's handle */ 
int Used to cycle through write modes */ 
int ffllete = used to cycle through circle fill styles */ 
int width; box width set by graf_rubbox */ 
int height; box height set by araf_rubbox */ 
Int X coordinate of atlipsats center */ 
int Y coordinate of ellipse's center */ 
int : 7X radius of ellipse */ 
77 radius of ellipee */ 


opel 
sraf_nouse(ARROW, Enowhere); 
graf handleCéneunere, Enovhere, Srovhere, Erovhere)? 
vopewaktwork_in, vdthandle, wrk_out); 
ve_cliptvaihardle, 1, cliparray): 
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‘vet_interior(wihandie, 2 
vst perimetertvdinandle, 1); 
van_height(inandle, 33; 
forts3) « 
‘selection = ext multi(unich, clicks, button, 20m, 
0, rorect, 0, norect, buffer, 0, 0, Enousex, tncusey, 
Enoiere, nowhere, Bkey, Snownere! 


suiteh¢selection) ¢ 
cence MU_KEYBO: 

FF (key == RETURK) ( 
‘v.clawdk(wdthandl ed; 
appl_eritO; 
exir(0); 

ey 


Af (hey == KEY) ( 
writectres; 
‘vaur_sede(idinandie, (writectrt4jet 


> 
beat 


‘case BUTTON: 
filletress 
vet_style(vdihardte, (f)ltetri26)+9); 
aray_rubbox(ecusex, mousey, 0, 0, dwidth, 2height); 
xcootd * mousexs(width/2); 
vyeoord = mouseys(helght/2); 
redius » wiath/ 


Yrodius = neigne/2; 
viellipsetudihandle, xcoord, yeoord, xradius, yradius); 


> 
See Also 
TOS, VDI, y_ellarc, y_ellpie 
Notes . 
y_ellipse can only create ellipses that are oriented horizontally or verti 
cannot create ellipses that are oriented diagnonally. 


¥_¢llpie—VDI function (libydi.a/y_ellpie) 
‘Draw an elliptical pie slice 
include <aesbind.h> 
#Include <vdibind.h> 
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y_enter_cur-y_fillarea 


void v_ellpie(handle. xcoord. yeoord, xradius. yradius. 
‘eginangle, endangle) 
int handle, xcoord, yeoord, xradius, yradius, beginangle, endangley 


y_elipie is @ VDI routine that draws an elliptical pie slice. Aandle is the virtual 
device's VDI handle. xcoord and yeoord give, respectively, the X and Y coor- 
dinates of the imaginary ellipse of which _ellpie draws 2 part. xradius gives 
the imaginary ellipse’s horizontal radius, and yradius gives its vertical radius. 
Finally, beginangle and endangle give, respectively, the beginning and end 
angles of the pie slice, in tenths of a degree. On an imaginary clock, zero de- 
grees is af 3 o'clock, 90 degrees at noon, 180 degrees at 9 o'clock, and 270 de- 
grees at 6 o'clock, 


See Also 
TOS, VDI, y_ellipse 


¥_enter_cur—VDI function (Iibydi.a/y_enter_eur) 
~ Enter text mode 

winclude <aesbind,h> 

#include <vdiblad.h> 

void y_enter_cur(handle) int handle; 


y_enter_cur is a VDI routine that moves a virtual device into text mode. It 
hides the mouse pointer and draws the text cursor. hardle is the virtual device's 
YDI handle 


See Also 
TOS, v_exit_eur, VDI 


cue YDI function (libydi.a/y_exit_eur) 
Exit from text mode 

#include <aesbind.h> 

#include <vdibind.h> 

void y_exit_cur(handie) int handle: 


y_extt_eur is 2 VDI routine that forces a virtual device to exit from text mode 
and return to graphics mode, should these modes be separate on that device. It 
Temoves the text cursor from the device and restores the mouse pointer, should 
the virtual device support them. handle is the Virtual device's VDI handle, 


See Also 
TOS, y_enter_eur, VDI 


* fillarea—VDI function (libydl.a/y_fillarea) 
Draw a complex polygon 
#include <aeshind.h> 
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#include <vdibind.h> 
void y_fillarea(handle, count. xyarray) int handle, coune, xyarrayteh, 
y_fillarea is a VDI routine that draws and fills a complex polygon. Nate 


use the Full power of this routine, you must first set the fill type with wsf. 
terior, the fill style with vsf_style, and the fill color with vsf_color, 


handle is the virtual device's VDI handle. count is the number of corners on 
polygon. xyarray gives the X and Y coordinates for each of the corners: al 
the even-numbered entries hold X coordinates, and all the odd-numbe 
entries hold Y coordinates. Note that the value of » must be exactly double 
of count, 

Example 

The following program draws a filled polygon on screen. Use mouse to) 
markers on the screen, with a maximum of 40 points. Pressing <esc> “co 
the dots” to draw and fill the polygon. Pressing the ‘T’ key cycles tht 
types of Fill; pressing the 'S’ key cycles through styles of fill. Pressing <re 
exits. 

Ainelude <gendets.t» 
Hirelude <oeabind.ty 
Winelude evdibind.t> 


def ine RETURK 0x1000 


+ scan code for <ceturr> key */ 


det ne ESC Ox118 7 sean code for cesc> key */ 
fisef ine T KEY 041474 77 sean code for 1 key */ 
Aidet ine STREY ORNF7S 7* scan code for $ key */ 


iiset ine ASTERISK 3 
[7 gtobal Line A varfablen used by vil; MUST be included "7 

int contel 121, Intint126), ptaintt2s), sntoutt28), prsouttt2e); 
J areay used by + pmarkert) */ 

(nt xymarker {2}; 

/* array used by v.f{\Llareac) */ 

ft xypoly 180); 

Pr array used by vi clip) */ 

Noe etipareeytr = C1, 1, 439, 3999: 

[7 arrays used by vopak() */ 
fine work int) = ty 4, 3, 4 1 
int work out i571; 


WU 2H 


[7 throwaway declarations, to keep system from scribbling over itself */ 
int nownere = 
Rect norect = (0,0, 0, 033 


y_fillarea 


maint) € 
Fe declarations used by emt_mul 


ay 


int selection: (7 code for evant that occurred */ 
Uncloned int which = (WU KEYBD | MU_SUTTOND; 
nt clicks = 1; 7? te. of clicks expected on mouse buttan */ 


Hd 


nt button J shich button; 1 = Leftnost */ 


int buttonetate = 7% button state expected; 1 = down */ 
int buffer (11; % place to write AES messages */ 

int mousex; [7 mouse X coordinate */ 

int mousey; fr mouse 7 coordinate */ 

Uns lane Key (Rey types by user */ 


/* wise declarations */ 
int vaihandt 


/* virtwal device's hendte */ 


nt type = 0; [type of FU */ 
Int style = 4; 77 style of fill */ 

int n= 0} /* used with xyarraytl */ 

int flog * 0; 7 bas polygon been droun yet? */ 


79K, bere We 90 ++. */ 
sppl_intteoy 

graf _mouse(ARtOY, Lnownere): 

vdihandle = grat handlecincuhere, knowhe 
Vopnwak(work in, Bvdthandie, work out; 
vi_eliptvdihandte, 1, eliparray); 


vsm height vdihandle, 3); 
‘vem_type(udthandle, ASTERISK); 


€ 
selection = emt multi(ubich, clicks, butten, buetonste 
D, rorect, 0, norect, buffer, 0, 0, knousex, kooutey, 
Lnoahere, ‘Anahere, they, Srowhere); 


suitehiselection) ¢ 
ease Mi KEYED: 
Suiteh(key) € 
cease RETURD 
velswde(vdihandle): 
spL_exit; 
exitto; 


+ bnowhere, bnovhere); 


forts? 


case ESC: 
‘rat_mouse(K OFF, knowhera); 
vfillereatvaihandte, rv2, xypoly); 
sraf_neuse(H_ON, knovhere);: 
flag = 
break; 
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vet_interfortwathandie, type); 
rai _nouse(HOFF, Enowhere); 
vAilorea(vaihandle, 12, xyp0lY) 
Faf_eouserM_O, roster 


cane SXEY: 
Wf (flag == 0) ¢ 
‘bre 
2 alee ¢ 
atyle = (coastyl ere) 


arat_souse(H OFF, nowhere); 
‘¥vAillareacvdinardte, 1/2, xypoly): 
grat_mouse(W OW, bnowhere); 


sxymarker{0) = sousen; 
ymerker() = mousey} 


n= 79) ¢ 
aypolyini = seusex: 
sypolytn}  aousey; 
> 


arat_nouse(M OFF, Inouhere); 
¥ pmarker(vdihandle, ASTERISK, somarker); 
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y_form_ady-y_gtext 


See Also 
TOS, »_bar, VDT, vr_recft 


_form_ady—VDI function (libydi.a/v_form_ady) 
‘Advance the page on a printer 
winclude <aesbind.h> 
include <vdibind.h> 
yold »_form_adv(handle) int handie; 


¥ form _ady is a VDI routine that advances the page on a printer. Unlike the 
related Function y_clrwk, y_form_ady does not erase material that has not yet 
been written onto the printer. 


See Also, 
‘TOS, ¥_clear_disp_list,y_clrwk, VDI 


\_get_pixel—VDI function (Itbvdi.a/y_get_pixel) 
if a given pixel is set 
Jude <aesbind.h> 
Jude <vdibind.h> 
oid y_get_pixel(handle, xcoord, yeoord, &flag. &olor) 
1 handle. xcoord, yeoord. flag, color; 


y_get_pixel is a VDI routine that indicates whether or nota pixel is set, handle 
is the Virtual device's VDI handle. xcoord and ycoord are, respectively, the X 
and Y coordinates of the pixel in question. flag is set by v_get_plxel; zero in- 
Vicates that the pixel is not set, whereas one indicates that it Is set.’ Finally, 
set by v_get_plxel; if the pixel is set, this variable holds the code of the 
color to Which itis set. For a table of color codes, see the entry for v_opnwk, 
See Also 
ros, VDI 


)_gtext—VDI function (libydi.a/y_gtext) 
Draw graphics text 
include <aesbind.h> 
include <vdibind.h> 
void v_gtext(handle, xcoord. yeoord. text) int text, xcoord, ycoord; char *text; 


»_gtext is ¢ VDI routine that draws graphics text on the screen. handle is the 

virtual device's VDI handle. xcoord and ycoord are, respectively, the X and ¥ 

coordinates of the point on the screen where the drawing of the string will 

begin. Note that these vslues will change, depending upon the virtual device 

has been set to normalized device coordinates (NDC) or raster coordinates (RC). 
ally, text points to the string to drawn. 
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‘The font of the string drawn. its size, its color, the angle at which it is 


played, and the manner of its alignment can all be set with separate VDI g 
See the entries given below for more information. 


Example 

The following example draws cross-hairs on the screen, and then ali 
string “Mark Williams C” against them. Pressing the 'E" key cycles throu 
available special effects; ‘H’, the available horizontal alignments; *R', the. 
rotation; ‘S', the available font sizes; and ‘V’, the vertical alignments. Ty, 
<return> exits from the program 


Hinelude <gembete.bo 
Winelude <nesbind.h> 
Winelude <vdibind. > 


det ine RETURN Ox1C00 / scan code returned by return Key "/ 
def ine E KEY Ox1265 7 scan code returned by E key */ 

fet ine WKY On2%68 7 wean code returned by H key */ 

fide ine KEY Oxt372 7 wean code returned by 8 key */ 

fidot ine STKEY OX}7S 7 scan code returned by $ key */ 

Wet ine VIKEY Ox2I76 17 sean code returned by V key */ 
fetine RESERVED ¢ 77 used by systen for {ts on purposes * 
fet ine ESCAPE 0x18 7 ASCU1 code for <ese> * 


7* global Uline A variables used by vil; MUST be included */ 
int contel 12), intin{ 281, pesintt28i, intout(128), pesouc (128; 


7° array used by ve_eltpC) */ 
int eliparrayD = C1, 1, 639, 397 
77 enemys used by deout ine) */ 

ayvert(] = (320, 1, 320, 399 9; 

wyhoriz0) = C4, 200, 639, 200 
Jt steing used by deawtexte) */ 
‘char text = "mark WiLUlame © 


(77 arrays used by v_opikt) */ 
int working = C1, 1 1 
Ine workout (5732 


UP throwaway dec 
int nowhere = 0; 


fon, to keep systen from scribbling over itself #/ 


maint ¢ 
unsigned key ([* key typed by user */ 
nt. ydthandt 7 virtual device's handle */ 
int size 7 text's size, |n rasters */ 
int effect (ft text's special effect used */ 
int hatign (7 text's horizontal aliganent */ 
Int vation [7 tontte vertical altanment #7 
nt angle = 7 angle at bch text fs draun */ 


y# 0, here we 90 «45 4/ 
appl_inito; 
aref_mouse(M_OFF, Enovhere); 
vaihandle = graf handlecinouhere, Bnovhere, Incwhere, Enoshere): 
v_opove(work_ in, Evdihandte, work out); 
Ys cliptvdinandle, 1, clipartay: 
rawtext(vdihendiey; 


fertsz) ¢ 

key = emt. keybdt 

ewitehikey) ¢ 

‘cone RETURA: 
srat_mouse(H ON, Bnovhere 
vclevek(vdihandied; 
appl exit0; 
exition; 


cane KEY) 
Vat effectstvdihandle, effect); 
(1 Gosetfect > 323 
effect = 
drevtentivdihandiey; 
bre 


cose KKEY: 
hal ionees 
‘st_alignment(vdihardle, chal gn), (val janté), 
nowhere, knower); 
77 Vegat'H vaiue 0-2, V value 0-5 */ 
drovtent(vdthardle); 
break; 
case RKEY: 
7 Note: ST dravs text enly at right angles */ 
angle += 900; 
Wt (angle > 3500) 
‘angle = 0; 
vst rotation(wdihandte, angle: 
drovtext(vdihandted; 
reek 


case SKEY: 
‘vat height(vdihandle, size, Enoshere, 
"e, knoshere, Ineshere) 
(7 character size in rasters */ 
If (resize > 26) 
size= ty 
Srentext(yaihandied; 
bre: 
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hardcopy 


cose V.KE! 
“vat ignres 
vst_aligrment(vdihandle, (halignXS), (val ignté), 
nowhere, Enowher®) 
7 Legal’ W value 0-2, V value 0-5 */ 
dravtext(vdihandle); 
break; 
default: 
break; 


> 


> 


drawl ines thandte) 

int handle; 

Ss 
vplinethandle, 2, xyvert); 
Viptinechandle, 2, xyhor!2); 
return; 


> 
rawtextthondley 


vclrkchandl 
dra inesthandl 
v_gtext hand) 
return: 


320, 200, ext); 


See Also 

‘TOS, y_Justified, VDI, vqt_exteat, vqt_name, yqt_width, yst_alf 
yst_color, vst_effects, vst_height, vst_load_fonts, vst_point, vst_s 
yst_unload_fonts 


y_hardcopy—VDI function (Iibydi.a/v_ hardcopy) 
Write the screen to a hard-copy device 
#include <aesbind.h> 
‘include <vdibind.h> 
void y_hardeopy(handle) 


y_hardcopy is 2 VDI routine that writes 2 copy of the virtual device toa pri 
OF other attached hard-copy device. handle is the virtual device’s VDI hal 


See Also 
TOS, VDI 
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sexicon y_hide_c-y_justified 


Notes 
‘The printer must be installed with TOS before this routine will work properly. 


y_hide_c—VDI function (libydi.a/y_hide_c) 
Hide the mouse pointer 
include <aesbind.h> 
include <ydibind.h> 
void y_hide_e(handle) int handle; 


y_hide__c isa VDI routine that hides the mouse pointer. This routine should be 
invoked when your program redraws the screen; if the pointer is not hidden, it 
will leave a grayish patch on the screen when it is moved. 


See Also 
TOS, y_show_c, VDI 


tified—V DL function (Iibvdi.a/y_justified) 

Justify graphies text 

¥include <aesbind.h> 

#include <vdibind.h> 

void v_justified(iandle, xcoord. ycoord. string. length, charsp. wordsp) 
int handle, xcoord. yeoord, length, charsp, wordsp; char *string; 


\_justified is a VDI routine that justifies « string a text on a preset line length, 
Justification means that slivers of space are inserted between words or charac- 
ters to ensure that each string fills exactly the same space. This paragraph is an 
example of justified text, 


handle is, as always, the virtual device’s VDI handle. xcoord and ycoord give, 
respectively, the X and Y coordinates of the point where the text is to begin 
printing, length is the length to which you want the text set; this value will 
vary, depending on whether the virtual device is set to normalized device coor- 
dinates (NDC) or to raster coordinates (RC), string points to the string you 
want to set. Finally, charsp and wordsp are flags that indicate whether you 
want spacing altered between words or characters when performing justifica- 
tion; zero turns off spacing, and one turns it on. Therefore, setting both charsp 
and wordsp to zero effectively turns off justification. 


Note that if the string is too long to fit into space, the characters will overlap. 


See Also 
TOS, y_gtext, VDI 
Notes 


‘This routine uses the VDI's GDOS in its operation. It should not be used if the 
GDOS is not present in your edition of VDI. 
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y_meta_extents—VDI function (libydi.a/y_meta_extents) 


y_opiywk—VDI function (Hibydi. 
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Update extents header of metafile 

#include <aesbind.h> 

#include <vdibind.h> 

void y_meta_extents(handle. minx. miny, maxx. maxy) 


int handle, minx, miny, maxx, ma: 


¥_ meta_extents is a VDI routine that updates the extents header of a meta 
The extents header gives the minimum space needed to draw all of the 
primitives contained in the metafile; it is used by some routines in alloca 
space. handle 
tively, the minimum width and height of the area needed to hold the 
primitives contained within the metafile; whereas maxx and maxy give, respes 
lively, the maximum width and height. 

See Also 

TOS, y_write_meta, VDI, ym_fllename 
Notes 

This routine uses the VDI's GDOS in its operation. 1t should not be used if th 
GDOS is not present in your edition of VDI 


If this routine is not used when an item is added to a metafile, the extent 
parameters will be set to zero. 


the virtual device's VDI handle. minx and miny give, respoes 


_opnywk) 
Open the virtual screen device 

Winclude <aesbind.h> 

#iuclude <vdlbind.h> 

void y_opnywk(work_irt, handle, work _out) 
int work_inl11], *haridle, work_outlS7F; 
y_opnywk is a VDI routine that opens the virtual screen device. work in ie am 


array of I] integers that must be set before invoking v_opnywk, These 
described in the entry for v_opnwk. 


handle is the device handle for the screen. Because the desktop has alrea 
‘opened the physical screen device, you must use the AES routine graf_hand 
to obtain the VDI handle for the screen, as follows: 


foo = graf_handlettkcoord, Aycoord, twidth, theraher; 


Tn this example, foo is the VDI handle, which is returned by graf_handle 
xcoord, ycoord, width, and height give the dimensions of a character cell in 
soreen device, and are'set by graf_handle. 


work_out is an array of $7 integers that are set by v_opnywk. Your prog 


Mark Willia! 


‘pexico™ 


may need to interrogate this array for information; what each integer encodes is 
described in the entry for ¥_opnwk. 


Exeniple 
For an example of this routine, see the entry for y_pline 


See Also 
TOS, v_opawk, VDI 


nt, device attributes cannot be set through the work _in/array. With the 
exception Of work_in{10], they are all ignored and shouldbe set to zero. To 
set device attributes, use the appropriate attribute functions, as listed in the 
entry for VDI 


y_opawk—VDI function (libydi.a/v_opnwk) 
Open a virtual workstation 
#include <aesbind.h> 
¥include <vdibind.h> 
void y_opnwk(work_in, handle, work_out) 
Int work_inl 1], *havdle, work outlS7]; 


y_opnwk is a VDI routine that opens virtual workstation. This routine 
should used to open all virtual workstations except the screen, because the 
screen ig already set by GEM when it boots. To open the screen, use 
¥_opnywk. 


work_in isan array of 11 integers that must be set before y_opawk is invoked. 
Theit Values are as follows: 


Wwork_infO) Device number, as follows: 


1 screen 
11 plotter 
21 printer 
31 metafile 
41 camera 
SI tablet 


work_inf 1] Line type, as follows: 


solid 
long dashes 

dots 

dashes plus dots 
short dashes 

dash, dot, dot 
user-defined 
device-independent 
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work_in[2] 


work_in[3] 


work_inf4] 
work_in[5] 


work_in[6] 
work_in[7] 


Line color, as follows: 


0 
1 
2 
3 
4 
5 
6 
T 
8 
9 
10 
u 
12 
13 
14 
15 


16-n 


Note that the names in capital letters are mnemonics that 
defined in the header file obdefs.h. 


Marker type, as follows: 


Monsen 


Marker color, same as above, 


Text face, These can vary greatly, depending on the 
being opened. Fora list of the code and names of the the | 
available on a virtual device, use the function vqt_font_infa 


Text color; same as above. 
Fill type, as follows: 


WHITE 
BLACK 
RED 
GREEN 
BLUE 
CYAN 
YELLOW 
MAGENTA 
WHITE 
BLACK 
LRED 
LGREEN 
LBLUE 
LCYAN 
LYELLOW 
LCYAN 
device-independent 


dot 

plus sign 

asterisk 

square 

diagonal cross 
diamond 
device-independent 


hollow 

solid 
patterned 
cross-hatched 
user-defined 


seork_in(8] 


work _inf9] 
work_in{ 10] 


Fill style, There are 24 styles of patterned fill, and 12 styles of 
cross-hatching. Sce the entry for ysf_interior for a program 
that displays the fill styles. 


Fill color; same as above. 


Coordinate system. Zero indicates normalized device coor- 
dinates (NDC). This is a system in which the screen is divided 
into a grid of 32,768 by 32,768 points, with the beginning point 
in the lower left-hand corner, Two indicates raster coordinates 
(RC), This uses the absolute number of rasters on the screen, 
counting from the upper left-hand corner of the screen. Note 
that the umber of rasters varies with screen resolution: high 
resolution is 640 wide by 400 high; medium resolution, 640 wide 
by 200 high; and low resolution, 320 wide by 200 high. At 
present, the Atari ST can accept only raster coordinates. 


handle is the device's VDI handle, and is set by TOS. 


work_out isan 


array of $7 integers that is filled in by y_opnwk, as follows: 


width of device, in rasters (no. of X coordinates) 
height of device, in rasters (no. of ¥ coordinates) 
uses precision scaling? (O=yes, !=no) 

width of one pixel, microns 

height of one pixel, microns 


no, 
no. 
no. 


no. 


no. 
10. 


no. 


0. 
no, 


no. 


. of possible character heights (O=continuous scaling) 


of line types 

of possible line widths (=continuous scaling) 
of marker types 

of possible marker sizes (Oecontinuous scaling) 
of text fonts available 

of fill styles available 

of cross-hatching styles available 

of colors that can be shown simultaneously 

of generalized drawing primitives (GDI's) 


first 10 GDI's supported (~1=end of list); 
lerectangle, 2=curve, 3=circle tegment, 
4scircle, Smellipse, 6=elliptical arc, 
7=elliptical segment, 8=rounded rectangle, 
Gafilled, rounded rectangle, 10=justified text 
attribute of corresponding GDI from 


wo 


rk_out{15}-[24] (-1=end of list): 


O-line, 1=marker, 2=text, 3=area fill, 
4eno attribute 

color capability? (O=no, !=yes) 

text rotatable? (0=no, |=yes) 

can fill areas? (0=no, 1=yes) 
supports cell arrays? (Q=no, I=yes) 
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39 no. of colors supported: 
O-more than 32,767; I-monochrome; >2-no. of colors 

40 Cursor control devices: |=keyboard only; 2=keyboard and 
mouse 

41 no. of mappable devices: l=keyboard, 2=another device 

42 no. of choice devices: I=function keys, 2=another key field 

43 no. of string devices: !=keyboard 

44° workstation type: O-output only: 1=input only; 

input/output; 3=reserved; 4=metafile 

4§ minimum character width 

46 minimum character height 

47 maximum character wicth 

48° maximum character height 

49 minimum visible line width 

50 reserved (always zero) 

$1 maximum line width in X axis 

52 reserved (always zero) 

53. minimum marker width 

$4 — minimum marker height 

SS maximum marker width 

56 maximum marker height 


See Also 
TOS, VDI, y_opaywk 


Notes 


GDOS is not present in your edition of VDI. To open the screen device, 
related function y_opaywk. 


As of this writing, a virtual device cannot have its attributes set throu 
work_in array. work_in/O] through work_in(9) should be set to om 
work_in{ 10] should be set to two. Any other settings will either be igno 
will Cause system errors. 


Dump a portion of a virtual device to a pri 
#include <aesbind.h> 
include <ydibind.h> 
void y_output_window(handle, xvarray) int handle, xyarray 


y_output_window is 3 VDI routine that dumps 8 portion of a virtual di 
the printer. handle is the virtual device's VDI handle. xyarray gives the 
corners of the area to be dumped. On devices set to normalized de 
dinates (NDC), eyarray/O] and xyarray/1] give, respectively, the X 
coordinates of the lower left-hand corner, and xyarray(2) and xyarray/3/] 
the coordinates of the upper right-hand corner, On devices set to raster 
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¥_pieslice-y_pline 


dinates (RC), the first two array elements give the coordinates for the upper 
jeft-hand corner, and the latter two elements the coordinates of the lower 
right-hand corner. 


See Also 
Tos, VDI 


Notes 
The printer must be correctly described to TOS before this routine will work 


¥_pieslice—VDI function (libydi.a/v_pieslice) 
—" Draw a circular pie slice 
winclude <aesbind.h> 
include <vdibind.h> 
void »_plestice(handle, xcoord. yeoord. radius. heginangle. endangle) 
int haiidle, xcoord, ycoord, radius. beginangle, endangle; 


¥_pieslice is a VDI routine that draws a circular pie slice. handle is the viriwal 
device's VDI handle, xcoord and ycoord give, respectively, the X and Y ccor- 
dinates for the imaginary circle of which the pie slice is a part. radius gives the 
imaginary circle’s radius. Note that these measurements vary, depending on 
whether the device uses normalized device coordinates (NDC) or raster coor- 
dinates (RC), Finally, beginangle and endangle represent the beginning and 
end angles of the pie slice, given in tenths of a degree. Counting on an imagi- 
nary clock, zero degrees is at 3 o'clock; 90 degrees at noon; 180 degrees at 9 
o'clock; and 270 degrees at 6 o'clock, 


See Also 
TOS, ¥_cirele, VDI 


¥_pline—YDI function (libydi.a/y_pline) 
Draw a line 
#inelude <aesbind.h> 
#inelude <vdibind.h> 
yoid v_pline(handle, howmany, xyarray) 
int handle, howmany, xyarray|l; 


¥_ pline is a VDI routine that draws a line. Note that for VDI, a line is built out 
of one or more line segments, each end of which has its own pair of X and Y 
coordinates. Thus, it is possible to use v_pline to draw polygons or other 
Figures on the screen. 


handle is the virtual device's VDI handle. count is the number of line segments 
to be drawn. xyarray is an array of integers that holds the X and Y coordinates 
for the ends of the line segments; n is exactly double the value of count. Note 
that each even value in the array encodes an X coordinate, and each odd value a 
Y coordinate. 
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Example 
The following example allows you draw lines on the screen while using 
mouse. Click the left button to draw a line; holding down the left button | 
you draw a continuous squiggle. Exit by typing any key. 


The program is called line.c. Compile it with the following command line; 
ce V Linece ~Laes -Lvdi 


This program should not be compiled with the -VGEM because it uses ar 
arge. 
‘The command line takes four arguments: the width of the line being dra 
(from one to 99); the type of line being draw (from one to six), and the 
endpoints (from zero to two), For example, to invoke the program from 
draw solid lines three rasters wide, with arrowheads at each end, type: 

gem line 3111 
‘This will allow you to experiment with various widths and styles of lines, 
sing an incorrect value or an incorrect number of variables causes it to exit & 
‘an error message that, unfortunately, flashes very briefly on the screen, 
Winetude <oesbind.t> 


Winelude <pendete.t> 
Winclude <vdibind.to 


77 Globel Line A varfables used by vil; MIST be included */ 
int contrt {12}, intin( 128], pesintt28, intout 128), ptecuttt23; 


2 array used by viplinec) *7 
ine xyareaytd = € 1, 4, 1, 193 


J array used by viclip() */ 
Int eliparrayt) = C1, 1, 639, 347 95 
/* arrays used by vopwkc) */ 
int vork ind = C1, 1 ty My 
Int Work out i571; 


Wen 


7 theow-shey declarations, to keep system from scribbling over itself */ 
ine neowmere = 
Rect norect = (0, 0, 0, 09; 


siecarae, argv) 
The arger cher *eravOz ¢ 
/* declarations used by emt multi() */ 
int selection; 1/7 code for event that eccurred */ 
Unsigned int which = (MU_KEYB | ¥_BUTTOND; 
clicks = 17 to. of clicks expected on mouse button */ 
button r= shich button; 1 = leftmost */ 
buttonstate 72 button state expected; 1 = down */ 
buffer t111; 7 place to write AES messages */ 
smousex; 72 mouse X coordinate */ 
ovsey [+ mouse ¥ coordinate */ 


/* mise declarations */ 


int wlath; 
int type; 
int erty 
int ores 


/* check 1 comand Line arguments are OC */ 
Te ceargent) I= 4) € 
Quit (Usage: Line tuldth, type, end}, end2i 
ry 
Wiath = atotcargvit); 
type = atol(argvi2d); 
fendi © etoi¢argv) 
end2 = atol(aravisi); 


if Gaidth <1 |] width > 99) ¢ 


quit C*vidth fergy(11) has incorrect value"); 
ey 


Vt Ceype <9 I tre > 6.9 € 
Quit (ype fargv(2}} has (ncorrect value"); 
> 


Tf Cond) €0 [| ent > 29 ¢ 
quit (First Une end (argv(S3} has incorrect values); 
ey 
if (en@ <0 || wat > 2 ¢ 
‘quit (Second Line end fargvisld has incorrect value 
ey 
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graf mouse(ARROU, Eoowhere); 
Wdihandle = graf herdle(tnowhere, Enouhere, Enouhere, Enowhere); 
voprvak(werk_in, Evdthandle, work out); 

ve_eliptvainandle, 1, cliperrey); 

vsl_width(vdihandie, width); 

vsl_type(vdthandie, type) 
vsllends(vdinandie, end, end); 


forts) © 
selection = emt multiGAich, clicks, button, buttenatate, 
0, norect, 0, roreet, buffer, 0, 0, kocuKex, Ancusey, 
Brovhere, ‘Boowhere, Enovhere, knowhere); 


suitech(selection € 
‘cone MU_KEYBO: 
wetavuk(vdthandtey; 
oppl_exit0; 
exir00); 
cease M)_OUTTON: 
yarray(O} = xyarey{2); 
xyerray(N) = xyarrayi3); 
wyarray@2) = 
xyarrey®) 


> 


quittmessage) 
char "message; 


« 
printfomsin", message 
exit}; 

ey 

See Also 


TOS, VDI, vql_attributes, ys!_color, ysl_ends, ysl_type, vsI_udsty, vsl_) 


y_pmarker—VDI function (iby 
Draw a marker 
include <aesbind.h> 
#include <vdibind.h> 


2/¥_pmarker) 
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void v_pmarker(handle, count, array) int handle, count, arraytnh; 


+_pmarker is a VDI routine that draws one or more markers on a virtual device. 
andle is the virtual device's VDI handle. count is the number of markers you 
want to draw. array is an array of X and Y coordinates that locate each marker 
on the screen; n, therefore, must be exactly double the size of count. Every even 
number in this array indicates an X coordinate, and every odd number a Y 
coordinate. Note that the values for each coordinate will differ, depending on 
whether the device is set to normalized device coordinates (NDC) or raster 
coordinates (RC). 


Example 
For an example of this routine, see the entry for y_cirele, 


Sce Also 
TOS, VDI, vam_atteibutes, ysm_color, ysm_height, vsm_type 


y_rhox—VDI function (libydi.a/y_rbox) 
~ Draw’ a rounded rectangle 
include <resbind.h> 
include <vdiblad.h> 
vold v_rbox(handie, xyarray) int handle, xyarraytal; 


¥_rbox is a VDI routine that draws a rectangle with rounded corners, handle is, 
aS always, the virtual device's VDI handle, xyarray gives the X and Y coor- 
dinates of the two corners that define the rectangle; the even entries in the ar- 
ray give the X coordinates, and the odd entries the Y coordinates. Note that 
these values will change, depending on whether the virtual device is defined as 
using normalized device coordinates (NDC) or raster coordinates (RC). On an 
NDC device, xyarray/0] and xyarray/ 1] encode the lower left-hand corner, 
where on an RC device they encode the upper left-hand corner; likewise, on an 
NDC device xyarray/2J and xyarray/3) represent the upper right-hand corner, 
whereas on an RC device they represent the lower right-hand corner. 

Example 

The following example draws filled, rounded rectangles on the screen. Use 
mouse to draw rubberboxs on the screen, Pressing any key exits 

finelude <pencete.t> 

fineluse <eesbind. b> 

Finelude <vdibind.A> 


7 global Line A variables used by val; WST be Included */ 
nt contritt2}, intisti28), etsin{t28), intovt{128), prscut 1281; 
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1 array used by v_rfboxt) */ 
int xyarray = C1, 1, 1,19; 


J* array used by ve_clip() */ 
int eliperrayG = C1, 1, 639, 3992; 
JM arrays used by v_epwwkc) */ 
int workin = O11, 15 Vy 
Int work_out i573; 


bana 


/* throw-ouay declarstions, te keep systen from scritiling over itself */ 
Int nowhere = 0; 
fect nerect © (0, 0, 0, 09; 


maine) ¢ 
1 declarations used by emt_multi() */ 
int seleccion; (7 code for event that occurred */, 
Unsigned int wich = (WR KEYBO | BUTTON); 
int clicks = 1; 77 ro. of clicks expected on mouse butten 
int button = 7 sich button; 1 leftmost */ 
Int buttonstat 7% button state expected; = down */ 
nt buffer (11 7* place to write AES messages */ 
int mousex; 2 scuse X coordinate * 
nt mousey; 7 souse ¥ coordinate */ 
unsigned ke 7 key typed by user */ 
/* mie declarations */ 
int vaihardle; 7 virtual device's handle */ 
nt width; 7* width of rubberber user draws */ 
(nt depth: 7* depth of rubberbox user draws */ 


OT 0, here we 90 =: 


fF mouseCARRON, nowhere); 

vdihandle = grat’handle(Enowhere, Enounere, Enouhere, nowhere); 

¥opewwak(work_in, Evdihandle, wort ut); 

vi.eliptvdinardle, 1, ellparray) 

vet_perimeter(vdihandle, 1); 

‘ 

‘selection = evnt multi(ubich, clicks, buttan, buttonses 
4G, norect, 0, norect, buffer, 0, 0, &mousex, knousey, 
nowhere, Bnowhere, Hey, Enownered; 


forts: 


switentselection ¢ 
case Mi KEYED: 
Vclsvak (vdihandt 
sppl_exit( 
exizio 
break: 
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case Wy SUTTON: 
Grat_rubbox(neusex, meusey, 3, 3, Ewidth, depth); 
xyarray{0) = mouse: 
nyarrayif] = mousey; 
syarrayi2} = (nousextwidth: 
syarrey(3) = (neuseytcepth: 
graf_mouse(M_OFF, Erowhere); 
virfboxtedihandle, xyarray); 
‘af_mouse(H_ox, Enoxbere); 


See Also 
‘TOS, VDI, ¥_rfbox 


rthos—VDI function (libydi.a/y_rfbox) 
Draw a filled, rounded rectangle 
#include <aesbind,h> 
include <vdibind.h> 
void v_rfbox(handle, xyarray)) Int handle, xyarravls}; 


y_rfbox is a VDI routine that draws a rectangle with rounded corners. It uses 
the functions ysf_Interior and vsf_style, which set, respectively, the type and 
style of the interior fil, 


handle is, as always, the virtual device's VDI handle. xyarray gives the X and 
Y coordinates of the two corners that define the rectangle; the even entries in 
the array give the X coordinates, and the odd entries the ¥ coordinates. Note 
that these values will change, depending on whether the virtual device is 
defined as using normalized device coordinates (NDC) or raster coordinates 
(RC), On an NDC device, xyarray/0] and xyarray{1] encode the lower left- 
hand corner, where on an RC device they encode the upper left-hand corner; 
likewise, on an NDC device xyarray[2] and xyarray{3] represent the upper 
right-hand corner, whereas on an RC device they represent the lower right- 
hand corner. 


Example 
‘The following example draws filled, rounded rectangles on screen. Use mouse 
to draw a rubberbox on screen. Pressing any key exits, 
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include <pendets.h> 
#incluse <sex0ine.n> 
Finelude <vibire.h> 
ef ine RETURN Ox1C00 


Jf global tine A variables used by vii; MUST be included */ 

Int contrt (121, {ntintt28), ptsint126), intour(t281, ptecut 1281; 
7) array used by v_rfboxt) */ 
int ayareay = C7, 1, 1,1 
/* areay used by ve_clipt) */ 
ine eliparrayal = C1, 1, 639, 3999; 
(* arrays used by v_oomwe() 
int work ind = (1, 1, ty 
fnt workout (57); 
/* throw-auey deel 
int nowhere = 0; 
Rect norect * (0, 0, 9, 0 


of 


why 


29 


rations, to keep systen fron scribbling aver itself */ 


maing ¢ 
1 declarations used by emt multi */ 
int select on; (77 code for event that occurred */ 
Unsigned Int which = (HR XEYED | ¥L_BUTIOND; 
int clicks © 1; 7* po. of clicks expected on mouse button */ 
{int button © 1; 71 sich button; 1 = leftmost */ 
int buttonstate = 1; 7 button state expected; t= down */ 
int buffer(112; 77 place to write AES sessoges */ 
int mousex; 77 mouse X coordinate */ 


7 meune ¥ coordinate */ 
77 ey typed by user */ 


Ut virtual device's handle */ 


{nt widen; 7 width of rubberbox user deans */ 
Sint depth; 7° depth of rubberbos user dravs */ 
/* 0k, here we 90... */ 
eppl_init(o; 


arafnousecARROY, Erowhere); 

vaihindle = graf handle(Bnoshere, Enouhere, Bnohere, nowhere); 
voprwwk(work_In, Avdihandle, work out); 

Véeliptvdihandle, 1, clipartay) 
yet perimeter (vdihandle, 1); 


= ent_multi(uhich, clicks, button, buttonstate, 
©, norect, 0, norect, buffer, 0, 0, knousex, kaousey, 
Bewhere, Rnowhere, Hkey, Browhere); 


yrmeur-v_rvoff 


switehcsetect tony ¢ 
case WLKEY 
Velsvuk(vdihardley; 
apl_exitO; 
exit@0); 
case WU_BUTTON: 
graf_ribbottsousex, sousey, 3, 3, Ewidth, 
nyarray(O) = meusex 
xyarrayit} = mousey? 
nyatray[2} = (sousextwidth): 
xyarray(S] = (souseyedepth); 
graf mouse(M OFF, krowhere); 
v.rfbextwdihaadte, xyarray) 


) 
See Also 
TOS, VDI, y_rbox 


v_rmeur—VDI function (libydi.a/y_rmcur) 
Remove last mouse pointer from the screen 
include <nesbind.h> 
Winclude <vdibind.h> 
void y_rmeur(hand/e) int handle: 


y_rmeur is a VDI routine that removes the last mouse pointer from the screen, 
Note that this routine removes only the last mouse pointer to have been in- 
Voked. If the mouse pointer has been invoked several times, this routine must 
be called as many times before the mouse pointer finally disappear 

See Also 

‘TOS, VDL 


»_rvoff—VDI function (libydl.a/y_rvoft) 
End reverse video for alphabetic text 
#include <aesbind.h> 
#include <ydibind.h> 
Vold v_rvoff(hand/e) int handle: 


¥_rvoff is a VDI routine that turns off reverse-video display for all alphabetic 
text written subsequently. handle is the virtual device's VDI handle. 
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y_rvon—VDI function (libydi.a/y_rvon) 


y_show_e—VDI function (libydi.a/y_show_c) 


¥_updwk—VDI function (libydi. 


See Aiso 
TOS, y_rvon, VDT 


isplay alphabetic text in reverse video 
+#include <aesbind.h> 

#include <vdibind.h> 

void y_rvon(handle) int handle; 


y_rvon is a VDI routine that causes all subsequent alphabetic text to appe 
reverse video, handle is the virtual device's VDI handle 
See Also 
TOS, v1 


off, VDI 


‘Show the mouse cursor 

#include <aesbind.h> 

#include <vdibind.h> 

void y_show_e(handle. ignore) int handle, ignore; 


¥_show_c isa VDI routine that reshows the mouse cursor after it has been. 
den, Dae to a peculiarity in the VDI, this or a similar routine must be invoke 
the same number of times that the mouse pointer has been hidden, For. 
ample, if the mouse pointer was hidden three times in a row wi 
redisplayed, it must be recalled three times with y_show_e or a similar ro 
-_imouse) before it will reappear. 


handle ig the virtual device's VDI handle. ignore is a flag that sets the 

hide-mouse counting feature: zero indicates that the number of times the m 
pointer was hidden should be ignored, whereas one means that it shoul 
honored. 


See Also 
TOS, y_hide_c, VDI 


)_updwk) 
Update a virtual workstation 
include <aesbind.b> 

include <dibind.h> 

void y_updwk(handle) int handle; 


y_updwk is @ VDI routine that updates. virtual workstation. handle is the Y 
tual device's VDI handle. 


This routine is used with virtual devices that have buffered output, 


¥_write_meta-VDI 


exicom 


printers and plotters, and so is somewhat analogous to the STDIO function 
Flush. Note that this function merely executes the commands in buffer, but 
does not clear the workstation. To clear the workstation, use the function 
+ elewk 


See Also 
TOS, ¥_clewk, VDI 


Notes 
This routine uses the VDI's GDOS in its operation. It should not be used if the 
GDOS is not present in your edition of VDI. 


y_write_meta—VDI function (libydi.a/y_write_meta) 
—" Write a metafile item 
#include <aesbind.h> 
include <ydibind.h> 
void y_write_meta(handle, numintin, intin, numptsin, plsin) 
int havidle, numintin. intirdnumintin|, numptsin, pesinlnumptsinks 


y_wrlte_meta is a VDI routine that writes a VDI item into a metafile. The 
item is assigned an opcode by the VDI. handle is the virtual device's VDI 
handle, The intin and ptsin arrays hold the information needed to build the 
metafile item, The first entry must hold an opcode that describes the type of 
item being built. The next 100 entries are reserved by the system, The sub-op- 
codes used to build the item are entries 101 and higher. 


See Also 
metafile, TOS, y_meta_extent, VDI, ym_fitename 
votes 
This routine uses the VDI's GDOS in its operation, It should not be used if the 
GDOS is not present in your edition of VDI. 


VDI-Definition 
VDI stands for virtual device interface. The VDI is designed to provide the user 
With graphics routines that can be transported without alteration to @ variety of 
devices: screen, printer, plotter, video camera, graphics tablet, and “metafil 
The VDI can perform the following tasks on these devices 


+ Draw lines, polygons, circles, curves, and other graphics primitives. 


* Fill or flood areas with a preset pattern or cross-hatching 
* Copy (“blit") areas of the virtual device or graphics images. 


Load type fonts, and size, justify, and rotate graphics text, 
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Write and read “metafiles”, or a file of an image that can be incorpo 
into various other VDI programs (for example, company logo), 


Return information about virtual devices and drivers. 
Await user events and interrogate the system about them. 


Devices and virtual devices 

‘The VDI has drivers that support a number of physical graphics devices, 
physical device can, in turn, have output to it one or more “virtual devices" 4 
virtual device is a logical description of the physical device that is handed fo! 
device driver for display on the physical device. For example, you may of 
virtual device for the screen, which creates a logical description of the 
for your program to manipulate. Every time this virtual device is chang 
device driver updates the physical device to reflect this change. Note that m 
than one virtual device may be created for each physical device; this allo 

to create a series of “transparencies” that can be manipulated independent 
each other and overlaid on the physical device, 


Each virtual device can be described using either normalized device coord 
(NDC) or raster coordinates (RC), The NDC system divides a virtual d 
into a grid that has 32,767 points on each side. The size of points on 
scale differ from those on the Y scale, to ensure that object such as circle 
drawn in correct proportion. The RC'system uses the number of rasters on 
physical screen to scale its objects. The number of rasters will vary, depend 
fon the resolution t0 which the screen is set, as Follows: high resolutions 
horizontal and 400 vertical; medium resolution, 640 horizontal and 200 ver 
and low resolution, 320 horizontal and 200 vertical 

Note that the NDC and RC systems also differ in where they place the 0,0 po 
on their X/Y scales. In the NDC system, the 0,0 point is in the lower leftshg 
corner, whereas in the RC system, 0,0 is in the upper left-hand corner. Al 
jects drawn on the virtual device will be oriented in the same way; for e 

a rectangle drawn on an RC virtual device will be measured from the 4 
left-hand corner to the lower right-hand corner, whereas one on an ND 
device will be measured from the lower left-hand corner to the upper # 
hand corner. In general, RC are easier for the programmer to visuali 
handle, but NDC are more portable. 


VDI components 
‘The VDI, like Gaul, is divided into three parts: a library of fonts, a lib 
device drivers, and GDOS. 


The fonts display alphanumeric characters in various sizes, weights, and 
The device drivers turn generalized VDI statements into bits that can be 
stood by particular physical devices. Finally, the most important element 
graphic device operating system (GDOS). ‘The GDOS, as its name imp 
coordinates the loading of fonts and drivers, and ensures that’a virtual de} 
directed to the correct physical device. It ensures that the VDI is truly de 


independent, 


The GDOS also controls the writing and use of metafiles. These files are ex- 
traordinarily useful; for more information, see the entry for metafile. 


Programming with the VDT 

‘The VDI is “virtual” because it works not directly with physical devices, but 
with the logical description of a device, or a virtual device. When this lozical 
description is altered, the VDI can either update the phyical device directly or 
record the changes in’ metafile. 


To work with the VDI, a program must first open a virtual device with one of 
tie functions v_opawk or y_opnywk. To use these routines, you must hand 
them an array of 11 integers that set various aspects of the graphics environ- 
nent: for example, the color and thickness of the lines to be drawn, the color of 
the text, and the type and style of pattern fill for polygons. These routines as- 
sign a hand{e to the virtual device, and return an array of 57 integers that give 
information about the newly opened virtual device. 


The VDI, in its operation uses five global arrays of integers: Intin{], intoutl|, 
ptsinl}, ptsout{], and contri{]. The last of these should be declared as having 12 
members; the others should be declared as having 128. These arrays are 
manipulated directly by assembly-language programs, they are not used directly 
within C programs, but must be declared for the VDI routines to work, 


Within the program, you can use routines to draw graphics primitives, receive 
and process information from the user, modify the virtual device's default set- 
tings, and perform many other types of useful tasks. 


When finished, the functions y_elswk or y_elsywk should be invoked to free 
the memory used by the virtual device, and otherwise tidy up after the 
program. 


Note that all programs that use the graphics interface must run under the AES; 
this means that all programs that use the VDI must begin with appl_init and 
close with appl_exit. 


FDI library routines 

The VDI library routines are declared in the header file ydibind-h. and sre 
stored in the library Ibydi,a. These routines are, in turn, built out of the Atari 
Line A routines, which form graphic “primitives”. The following lists the VDI 
routines and gives a brief description of each. For more information about @ 
particular routine, see its entry in the Lexicon. 


y_are draw acireular are 

y_bar draw an outlined, 
y_bit_image print a bit-image fi 
yTeellarray create an array of colored cells, 
y_eirele draw acircle 
yoelear_disp_list clear a printer's display list 
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yelrwk 
yLelsynk 
yoelswk 
Y_eontourfill 
yeurdown 
y_eurhome 
yleurleft 
yLeurright 
yeurtext 
yLeurup 
yodspeur 


ecol 


yeeos 
yoellare 


y 


ellipse 


yrellpie 
yLenter_car 
yLexit_eur 
yfillares 
y_form_ady 
vget_pixel 
yogtext 
y_hardcopy 


v 


hide_c 


y_ Justified 
ymeta_extents 
y_opnywk 
yopnwk 
y_output_window 
y_piestice 
y-pline 
y_pmarker 
y_rbox. 

yorfbox 
yormeur 
yrveft 


¥ 


ron 


yoshow_¢ 
y_updwk 
y_wrlte_meta 
vex_buty 
vex_cury 
vex_moty 


vaeellarray 


cleara virtual device 

close the screen device 

close a virtual device 

draw a filled polygon 

move the text cursor down one row 
move the text cursor to upper left corner 
move the text cursor left one column 
move the text cursor right one column 
write a string of text characters 

move the text cursor up one row. 

move the mouse pointer to specified location 
erase from text cursor to end of line 
erase from text cursor to end of screen 
draw an elliptical arc 

draw an ellipse 

draw an elliptical pie segment 

enter text mode 

exit from text mode 

flood an enclosed area with fill pattern 
advance the page on a hard-copy device 
find if a particular pixel has been set 
output graphics text 

dump virtual device to hard-copy device 
hide the mouse pointer 

output justified graphics text 

update extents header of metafile 

open the screen virtual device 

open virtual device 

print a portion of a virtual device 

draw a circular pie segment 

draw a polyline 

draw a polymarker 

draw a rectangle with rounded corners 
draw rectangular fill area with rounded cornt 
remove last graphics cursor from screen 
turn off reverse video for text text 

turn on reverse video for text text 

show mouse pointer 

update workstation (flush buffers) 

add an item to a metafile 

change button interrupt routine 

change cursor movement interrupt routine 
change mouse pointer interrupt routine 
change timer interrupt routine 

rename a metafile 

‘query cell array information 
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yq_cheells 
tq_eolor 
vq_euraddress 
vq_extnd 
vq_key_s 
yq_mouse 
vq_tabstatus 
vaf_attributes 
yqin_mode 
val_attributes 
vami_attributes 
vqp_error 
vqp_films 
vqp_state 
val_attributes 
yat_extent 
vqt_font_info 
vqt_name 
vat_width 
ve_reefl 
yr_trafm 
yro_epyfm 
yrq_choice 
yrq_locator 
veq_string 
veq_valuator 
yet“epyfim 
vs_elip 

\s_ color 
saceeraatress 
¥s_palette 
yse_form 
ysf_color 
ysf_interlor 
ysf_perimeter 
ysf_style 
vsf_udpat 
ysia_mode 
ysl_color 
ysl_ends 
ysl_type 
ysl_udsty 
ysl_width 
vsmi_choice 
ysm_color 
ysm_height 
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query no. of characters printable on device 
Guery/set mix for a color 

query text cursor’s current position 
perform extended inquiry 

query keyboard status 

query mouse position and button state 
query if graphics tablet is available 
set fill area attributes 

set inquiry mode 

query polyline attributes 

query polymarker attributes 

query message from Polaroid Palette 
films supported on Polaroid Palette 
read status of Polaroid Palette driver 
query graphics text attributes 

query length of a string 

Quer information about fonts 

Query name and description of font 
Query width of a character's cell 
draw a rectangular fill area 
transform bit image format 

copy (blit) a portion of a device 
query choice devices, request mode 
Query locator devices, request mode 
query string devices, request mode 
query valuator devices, request mode 
copy (blit)-a monochromatic image 
clip an area of the virtual device 

set mix for a color 

move text cursor to specified point 
set the palette for medium resolution 
sel new mouse pointer shape 

set fill color 

set fill type 

set drawing of perimeter 

set fill style 

set user-defined fill pattern 

set mode of logical device inquiry 
set polyline color 

set polyline end types 

set polyline’s pattern 

set user-defined polyline style 

set polyline width 

‘query choice devices, sample made 
query color settings 

query character cell's height 


query locator devices, sample mode 


ysm_locator 


ysm_string ‘query string devices, sample mode 
‘ysm_type query graphics text attributes 
ysm_valuator query valuator devices, sample mode 
ysp_message suppress Polaroid Palette messages 
ysp_save ‘save settings of driver for Polaroid Palette 
ysp_state set Polaroid Palette driver 
yst_aligament set graphics text alignmment 
yst_color set graphics text color 
vst_effects set graphics text special effects 
yst_font set graphics text font 
vst_height set graphics text height, in pixels 

\f load non-standard fonts 
yst_point set graphics text height, in points 
yst_rotation set angle of graphics text 
ystlunload_fonts unload non-standard fonts 
yswr_mode set writing mode 


A sample VDI program 
The following program is a game that demonstrates how to use 2 quml 
VDI routines, The program draws a small black rectangle, which chases, 
mouse pointer. If the mouse pointer is caught, the program exults briefly, 
asks you if you want to play again. 


include <aesbind.h» 
‘inetd <gemdefs.h> 
Sinelude <oxbind.he 
Hinelude <vaibied.h> 


define BUTTON 1 (7° sich button; 1 = leftmost */ 
det ine CENTER 4 i Indicates centering of text */ 

fdef ine CENTERX 320, 7 X coordinate of center of high-res a 
‘define CENTERY 200 77 ¥ coordinate of center of high-res. 
‘define CLICKS 1 77 No. of clicks expected on mouse butt 
det ine DON [77 mouse button = down */ 

def ine HITINE 0 7 high word in tiner values */ 

define LEFT O 7 set text flush left */ 

fidet ine LOTIME S 7 Lew word in timer values; set to 3 Bs 
tidefine xOR 6 7 code for writing in X08 sede */ 


7+ global Line A variables used by vi; MUST be included */ 
int contri fi2l, ineint28), pesin{128, intout(128l, prsaut {128}: 


r 


array used by ve cllp(). Clipping array MIST be set; otherwise, 
+ Low memory will Be written over by graphics forms that extend 

+ beyond the edge of the screen. 

aa 

int cliparrayfl = C1, 1, 639, 399 9; 
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[7 arrays used by viopmake) */ 
ne workin = C1, NT We te te 29 


nt Work out i573; 


/* arrays used by veo. 


int shapet) = « 


OMFFFF, OMFFFF, 
OxFFFF, OXFFFF, 
OxFFFF, OXFFFF, 
OKFFFF, OXFFFF, 


top eat = ¢ shape, 16, 


08 screen = COL, 0, 
int oldarrayt) » ¢ 


epytat) to blit cat araund screen */ 
[? draw 2 solid black rectangle into nonory */ 

OFFER, ORFFFF, 

OMFFFF, OXFFFF, 

OKFFFF, OXFFFF, 

OKFFFF OxFFFF 


16, 1, 0, 1, 0, 0, 9; [1 source form block */ 
0, 8, 6, 0, 6, 6, 09; 7 target form block */ 
7* initial position on screen */ 


2, 0, 16, 16, CEMTERK, CENTERY, CENTERK+I6, CENTERYS16 


int newarraytd © ¢ 


7* c9u position on screen */ 


D, 0, 18, 16, CENTERK, CENTERY, CENTEAK+I6, CENTERYS16 


Jt throwaway declaration, to keep systen from sceitbling over teal t */ 


Int nowhere = 0; 


ring) ¢ 
int mousex © 
int mousey = 
int vathondt; 


here we 9° 


/* wouse X coordinate */ 
/* mouse Y coordinate */ 
7* virtual device's handle */ 


” 


7 open AES process */ 


appl_initOs 


mouse (DUSY_8CE, nowhere); 
7° open virtual device */ 


valhandie = of 
opera nor 


f_handleCknowhere, Enoshere, Lnovhere, knowhere) 
iy Avdtherele, work 940) 


FF set clipping rectengle */ 
vcliptvdihendie, 1, eLiperray: 


J bit cat inteiatly */ 
vro_epytm(vdinendie, X0R, oldarray, deat, Bscreen); 


fertss) ¢ 


7 wet moute pointers position */ 
vanouse(viihandle, knovhere, tncusex, Lnousey); 
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77 eneck cat's position vs. that of souse +) 
if (oldarrayi6]< mousex) 
rewarreylél += 6; 
else if (oldarraytt) > mousex) 
newarraylél -= 6; 
1f (oldarray(5) < mousey) 
pewarraytS) + 6: 
else if Colderray{s) > mousey) 
newarray(SI -= 6; 


Jf sot cat's kitty corner */ 
rewarray{6) = nevarray{sl » Mi 
nevarray{7} = nevarray(5) © 1 


/* syrchronize with sereen, then Blit cat */ 
Veyne(0: 

veo_cpyimtvdthendie, XOR, newarray, deat, kscreen} 
veoepytm(vdihandie, XO8, oldarray, beat, ksereen} 


7 shuffle cat's new array Into old array */ 
oldarrayt6) = newarray 6) 

‘olderray{S} = newarray(5); 
foldarray(6) = newarray(6); 
foldarrey7) = newarray(T); 


77 check If cat has caught mouse */ 

Vt (CabuColdarray(4) ~ mouex) <= 16) bb 
(absColdarray(S) + mousey) <= 16)) € 
Gotchacvdihandted: 
playagalin(vdinendlie); 


gotchacvdthandl e> 


int vaharal 


« 


char *text = “GOTCHAH: 


(/* set text ottributes */ 

vat_effects(edinandle, 32); 

jgrmert(vdihandie, CEKTER, 0, Enowhere, nowhere); 
vethelght(vdinendle, 24, Knowhere, Rnowhere, nowhere, Enouhere): 


(/* ring the belt and write "GOTCHAI™ on sereen in big Letters */ 
Ceonout(*\07"); 

v.gtexttvditandle, 320, 200, text): 
ceent_tiner(1500, MITINE: 


pleyeseintvathendie) 
int vdihandle: 
‘ 
char *string = "21 Play again?3 f¥es|o! 
int button; 


(/* reset text attributes */ 
vst effects(vdihardle, 1 

vet_alignment(vdihardie, LEFT, 0, Breshere, Bnoshere}; 
vethefght(vaihandle, 13, Knouhere, inewhere, anouhere, 


/* draw alert bor */ 
button = formalert(t, string); 


1" do sbat user requests */ 
if tbutton == 1) ¢ 
77 ie., if user vant anether game... */ 
7 2. clear sereen again... °/ 
Fake wdihnandt 
F* +5 reset cat's position to center of screen... */ 
fewarray{al = oldarray{e) = CEVTERX; 
nevarray{51 * oldarray{S} * CENTERY; 
ewarray{6) = oldarray{6) = (CENTERK + 16; 
neworray{7) = olderray(7} = (CENTERY + 16); 
[Poe and redraw cat */ 
‘ro_epyfaivdihandie, x08, oldarray, Keat, Bscreen); 
(J return pointer shepe to bee */ 
‘rot _nouse(BUSY_BEE, Lnowher 
7 wait a few moments 20 user can get a 
fevnt_timer(1000, AITINE; 
return; 


user wants to quit */ 
7 close virtual station, close application, and exit */ 
vaclswk(vathandled; 

spl exlt(0; 


2 


See Also 
AES, libydi metafile, TOS, vdibind.b 


Notes 

At the time of this writing, the GDOS portion of the VDI is not included with 
TOS, This means that metafiles, most device drivers, most fonts, and device 
independent features are not available to the programmer, At present, the VDI 
supports drivers only for the screen device, and acknowledges only raster coor- 
dinates. A RAM version of GDOS will be made available to programmers, al- 
though as of this writing, no release date has been set. For more information, 
see the article “Pursuing the Elusive GDOS", by Tim Oren, in the summer 1986 
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vdibind.k—Command 


version—Command 


530 


issue of START. 
Note that both the AES and the VDI use trap 2 to access the services. 


Declarations for VDI and AES routines 
#include <ydibind.h> 


vdibind.h is the header file that holds declarations and definitions for the GEN 
YDI routines, which are contained in the library libydi.a. 


For a full description of these routines, see the Alari ST GEM Programme 
Reference, 

See Also 

AES, header file, TOS, VDT 


Print/create a version string 
version file .. 
version directory executable sourcefile 


version finds or creates a version string, When given an executable file as 
argument, yersion scans it for the version string, which it prints on the sta 
output device. 


version can also generate version numbers automatically, When given the n 
of a directory that holds source code, and the names of the execucahfe (whe 

for not it has been created yet) and sourcefile (or sourcefiles) version write 
brief program in assembly language that, when assembled and linked, g 

a version number for the program and writes it into the executable file. 


Example 
To generate a version number for an executable called color.pre that is 
piled from the source file called color.c, which is found in directory exat 
on drive B:, type the following command: 

version b\etumples color.peg colar -€ 2versien.s 
It does not matter what you name the file into which you direct t 
version; however, be sure that it has the suffix .s, so that the compiler will 
that it is an assembly-language file, and be sure to include its name on th 
command line when you compile the program. 


See Also 
‘as, commands, msh 


ii vex_butv-vex_moty 


al tab—Definition 
Mork Williams C recognizes the literal character *\v" for the ASCTT vertical tab 
character VT (octal 013). This character may be used as a character constant or 
in a string constant, like the other character constants: *\a', which rings the 
rudible bell on the terminal; *\b’, to backspace; '\F, to pass a formfeed com- 
mand to the printer; *\r', for a carriage return; and ‘\", for a tab character, 
The vertical tab character is whitespace; in particular, the macro isspace is true 
for \v'. 


verti 


See Also 
ASCIT, character constant 


yex_buty—VDI function (libydi.a/vex_butv) 
Set new button interrupt routine 
#include <aesbind.h> 
include <vdibind.h> 
void vex_butv(handle, address, oldaddress) 
int handle; void (*address); void (*oldaddress); 


yex_buty is @ VDI routine that lets you set a new button interrupt routine, 
handle is the virtual device's VDI handle. address is the address of the new in- 
terrupt routine. Note that your routine is responsible for saving registers and 
resetting registers. Finally, oldaddress, which is set by vex_buty, is the address 
of the old interrupt routine, 

See Also 

TOS, VDI, vex_curv, vex_moty, vex_timy 


Yex_cury—VDI function (Ilbydi.a/vex_eury) 
Set new cursor interrupt routine 
include <aesbind.h> 
#include <vdibind.> 
old vex_curv(handle, address, oldaddress) 
int handle; void (*address); void (“oldaddress); 
vex_eury is a VDI routine that lets you set a new cursor movement interrupt 
routine. handle is the virtual device's VDI handle. address points to the new 
interrupt routine. Note that your new routine is responsible for saving and res- 
toring registers. Finally, oldaddress, which is set by vex_cury, points to the old 
interrupt routine, 
See Also 
TOS, VDI, vex_buty, yex_moty, vex_timy 
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yex_timy-ym_filename 


vex_moty—VDI function (libydi. 


vex_thny—VDI function (libydi.a/vex_timy) 


\m_filename—VDI function (libydi.a/ym_filename) 


vex_moty) 
‘Set new mouse movement interrupt rout 
#include <aesbind.h> 

#include <ydibind.h> 

yoid vex_motv(iandle,. address, oldaddress) 
int handle; vold (*address); void (*oldaddress); 


yex_moty is a VDI routine that sets a new interrupt routine to be invoked 
the Mouse pointer moves, handle is the virtual device's VDT handle. a 
gives the address of the new interrupt routine. Note that your rout 
responsible for saving and restoring registers. oldaddress is set by vex_moty 
holds the address of the old interrupt routine. 


Sew Also. 
TOS, VDI, vex_buty, vex_cury, vex_timy 


Set new timer interrupt rout 
include <aesbind.h> 
#include <ydibind.h> 

void vex_timy(handle, address, oldaddress. &time) 
int handle, time; void (*address); void (*oldaddress); 


vex_timy is a VDI routine that lets you set a new timer interrupt 
handle is the virtual device’s VDI handle. address points to the address. 
new interrupt routine. oldaddress is set by vex_timy upon exiting, and | 
tains the old interrupt address. Finally, time is set by vex_timy upon 
and contains the interval of the interrupt call, in milliseconds, Note that 
new interrupt routine is responsible for saving registers and returning 
system, ‘The interrupt is reactivated by setting the old interrupt address. 
See Also 
TOS, VDI, vex_buty, vex_cury, vex_moty 


e 


Notes 
‘This routine is called vex_time in some bindings. 


Rename a metafile 

include <aesbind.h> 

#include <vdibind.h> 

void vm_filename(handle, filename) int handle; char * filename; 


ym_filename is 2 VDI routine that renames a metafile, handle is the vir 
device's VDI handle. filename points to the new file name: this must be af 


phabetic string that is terminated with a NUL character. 


void 


void-va_cellarray 


See Also 
TOS, y_meta_extent, y_write_meta, VDT 


Notes 
‘This routine uses the VDI's GDOS in its operation. It should not be used if the 
GDOS is not present in your edition of VDI. 


Definition 
In addition to the data types described in The C Programming Language, Mark 
Williams C also recognizes the data type void. vold applies onfy’ to a func 
declaration, and indicates that the function does not return a value. Using ¥ 
declarations makes programs clearer and is useful in error checking. For ex- 
ample, a function that prints an error message and calls exit to terminate a 
program should be declared void because it never returns. A function that per- 
forms a calculation and stores its result in a global variable (rather than 
returning the result), or one that returns no value, should also be declared void 
to prevent the accidental use of the function in an exprestion. For example, 
old curnor_postxy? 
int 95 
‘ 

rimeeCONSBYREREM, Ke ', yer 19; 
> 


could be used to write the current position of the cursor in a screen handling 
program. 


To add yold to the formal definition of C, amend the list of type-specifiers in 
Appendix A of The C Programming Language to include void. 


See Also 
declarations 


+q_cellarray—VDI function (Iibydi.a/vq_cellarray) 


Return information about cell arrays 
include <aesbind.h> 
‘#include <vdibind.b> 
void vq_cellarray(handle, xyarray, rowlength. rows, 
ellused, &rowused. &status, cellarray) 
int handle, xyarray, rowlengthl4), rows, cellused, rowsused, status, cellarcay{n\; 


¥q_cellarray is a VDI routine that returns information about an establishad cell 
array. 


handle is the virtual device's VDI handle. xyarray gives the X and ¥ coor- 

inates for the rectangle in which tho array is drawn. Note that these values 
will vary, depending on whether the device is set to normalized device coor- 
dinates (NDC) or raster coordinates (RC). On NDC devices, xyarray/0/ and 
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vq_cheells 


yq_chcells—VDI function (libydi.x/vq_chcells) 


xyarray[ 1] give, respectively, the X and ¥ coordinates of the lower left-hi 
corner of the rectangle, whereas xyarray[2} and xyarray[3] 

dinates for the upper right-handle corner. On RC devices, xyarray/0] 
xyarray[ 1] give, respectively, the X and ¥ coordinates of the upper left-hat 
corner, whereas xyarray/2] and xyarray[3] give the X and Y coordinates 9 
the lower right-hand corner. rowlength gives the horizontal length of the tab 
to be shown, in NDCs or RCs, and rows is the number of rows of cells i 
array, 


cellused is the number of horizontal cells used in each row. rowused gives tht 


number of rows in the array that were actually used. status gives the array's 
ror status: zero indicates that no errors occurred, Whereas a number grester 1} 
one indicates that a color value could not be found for a given cell, 


Finally, cellarray gives the array of colors actually displayed in the used cell 
n must be equal to the number of cells in the entire array, The color index 
be set to -1 if the color requested for a given cell could not be found. 


See Also 
TOS, v_cellarray, VDI 
Notes 


‘This routine uses the VDI's GDOS in its operation. It should not be used if th 
GDOS is not present in your edition of VDI 


Find how many characters virtual device can print 
Winclude <aesbind.h> 
winclude <ydibind.h> 
void vq_cheells(handle, &raws, &columns) Int handle, rows, columns; 


Yq_chcells is a VDI routine that examines a virtual device and returns the num 
ber of rows and columns of characters that can be printed on it. handle is the 
virtual device's VDI handle, rows and columns hold, respectively, the numb 
of rows and the number of columns of characters that can be printed on th 
virtual device. 


Example q 
The following example returns the number of rows and columns available: 
the screen device. f 


include <aesbind. ho 
Hinelude <vdibind.h> 


(/* global Line A variables used by val; MIST be Included +/ 
fine contri (12), intin{128}, pesin{%281, Intout 1281, ptsous (1281; 


Lexicon yq_color-vq_curaddress 


(t errays used by ¥opeke? 
int workin = 01, 1, 1, 
nt work outs 


main € 
int nowhere = 0; 
int vdihandie; 
int columns; 


oppl_initoy 
Wihardle = graf_handie(énownere, known 
vopewt(work in, Bvdihandle, workout: 
Wachee iscrdiherdie, rove, “Reolumms): 


re, nowhere, Enovhere); 


Printt(We. of ross SA\n", rows); 
Print¥(Mo, of colums: Xa\n", columns); 


v_elsiwe(wihandiey; 
oppl_exit@; 
arr: 


> 


See Also 
TOS, VDI 


¥4_color—YDI function (Iibydi.a/vq_color) 
Check/set color intensity 
#include <aesbind.h> 
#include <vdibind.h> 
void vq_color(iandle, color, flag. rgb) Int handle, color, flag, rgel3k: 


vq_color is VDI routine that checks or sets the intensity of a particular color. 
handle is the virtual device's VDI handle. color is the code that indicates which 
color you wish to check or modify: for a table of color indices, see the entry for 
y_opnwk. flag indicates whether you want to set the color, or merely check it 
zero indicates set the color, and ont indicates check it, Finally, rgb points to an 
array of three integers that, respectively, set the red, green, and blue guns on 
the color monitor. Each should be set to a level between one and 1,000, with 
one being the lowest setting and 1,000 the highest. 


See Also 
TOS, VDI, vq_extnd 


¥4_curaddress—VDI function (libydi. 
Got the text cursor's current pos 
#include <aesbind.h> 
Finclude <vdibind.h> 
void vq_curaddress(Aandle, drow. &columr) int handle, row. column; 


/vq_curaddress) 
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va_exind 


vq_exind—VDI function (ti 


536 


ras 
sof on the virtual device. handle is the virtual device’s VDI handle. 

column are set by vq_curaddress; they give, respectively, the row and 
column in which the text cursor is positioned. i 


See Also 
TOS, VDI, vs_curaddress 


di.n/vq_extad) 

Perform extend inquire of VDI virtual device 

‘include <nesbind.h> 

#include <vdibind.h> 

void vq_extnd(handle. type, work_oul) int handle, type, work_outlS7I; 


yq_extnd is a VDI routine that performs an extended inquire on a virtu 
device. handle is the virtual device's VDI handle. type is the set of values 
want written into the array work out; zero indicates that you want the same 
values returned by functions y_opnwk or »_opnrwk. See the entry fo 
+_opnwk for a table of these values. Setting type to a non-zero value writes 
extended inquiry values into work out. 


The following tble gives the index into the work_out array, plus the valu 
written there by the extended inquiry; 


0 screen type: O-not a screen; I=separate alphabetic 

and graphics screens; 2=separate alphabetic and graphics 
controllers with common screen: 3=common alphabetic and 
graphics controller with separate image memories; and 
4=common alphabetic and graphics controller and common 
image memory 

no. of background colors available 
which text effects are available 
scaling possible? O=no, l«yes 

no. of color planes 

lookup table supported? O=no, !=1 
no. of 16X16-pixel raster operations done per second 
contour fill supported? O=no, 
can rotate characters? 10; 1=90 degrees only; 
2ecan rotate to arbitrary angles 

no. of writing modes 

highest level of input mode: O=none; 
2=sample mode 

11 text alignment supported? O=no; I=yes 

12 handles multi-colored pens (e.g., plotter)? Cano; layes 
13 handles multi-color ribbons (e.g., dot matrix printer)? 


request mode; 


14 maximum no. of points in a polyline: 


Jeno maximum 
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1$ maximum size of intin array: -I=n0 maximum 
16 no. of buttons on the mouse 
17 line types usable on wide lines? O=no; l=yes 
18 drawing modes available for wide lines 

19-57 reserved; contains zeroes 


See Also 

TOS, y_opnwk, VDI 

Notes 

‘This routine is called yq_extend in some bindings, 


yq_key_s—VDI function (libydi.a/vq_key_s) 
—"" Check control key status 
+#include <aesbind.h> 
vinclude <ydibind.h> 
void vq_key_s(handle, status) int handle, statuss 


'q_Key_sis a VDI routine that checks the control key status, handle is the vir 
tual device's VDI handle. status is « bit map that, upon return, indicates the 
status of the control keys; zero indicates not set and one indicates Set, as follows: 


0 right shift key 
1 left shift key 
2 control key 

3 alt key 


See Also 
TOS, VDI, vq_mouse 


¥q_mouse—VDI function (libydl.a/¥q_mouse) 
Check mouse position and button state 
#include <aesbind.h> 
#include <vdibind. b> 
vold vq_mouse(handle, &status, &xcoord, &vcoord) 
int handle, status, xcoord, ycoord; 


yq_mouse is a VDI routine that checks the mouse pointer's position and the 
status of the mouse buttons. handle is the virtual device's VDI handle. status is 
set by vq_mouse, and indicates the status of the mouse button: zero indicates 
not pressed, one indicates pressed. xcoord and ycoord are set by vq_mause and 
give, respectively, the X and Y coordinates of the mouse pointer. 


See Also 
‘Tos, VDI 
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¥q_tabstatus—VDI function (libydi.a/vq_tabstatus) 


Find if graphics tablet is available 
#include <aesbind.h> 

#include <ydibind.h> 

roid yq_tabstatus(handle) int handle; 


1q_tabstatus is a VDI routine that checks to see if the graphics tablet is ayail- 
able. hand(e is the virtual device's VDI handle. vq_tabstatus returns the status 
of of the graphics tablet: zero indicates that the tablet is not available, and one 
indicates that it is. 


See Also 
‘TOS, VDI 
Notes 


‘This routine uses the VDI's GDOS in its operation. It should not be used if the 
GDOS js not present in your edition of VDI. 


Vqf_attributes—VDI function (libydi.a/vqf_attributes) 


Read the area fill's current attributes 

include <aesbind-h> 

#include <ydibind.h> 

vold vaf_attributes( handle. attrib) Int handle. attribl\S; 

vaf_attributes is a VDI routine that returns the attributes currently set for the 
area fill, handle is the virtual device’s VDI handle, The fill area's attributes are 
‘written into the array attrib, as follows: 

auribfo] Fi 


attrib/ 1] Fill color, For a table of color codes, see the entry for y_opnwk. 


type. For a table of Fill types, see the entry for yst_interior. 


autrib[2] Fill pattern, For a table of fill patterns, see the entry for vsf_style. 


attrib[3] Writing mode: one indicates replace mode; two, transparent mode; 
three, XOR (exclusive or) mode; and four, reverse transparent 
mode. 


aitrib[4] Draw border: zero indicates that a border is not drawn around a 
filled srea, and one indicates that it will 


See Also 
TOS, ¥_bar, VDI, yql_attributes, yqm_attributes, vat_attributes 


ygin_mode—VDI functicn (libydi.a/yqin_mode) 


538 


Determine mode of a logical input device 
+#include <aesbind.h> 
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#include <vdibind.h> 
vqin_mode(handle, device, &mode) int handle. device, mode: 


ygin_mode is a VDI routine that retarns the current mode of a logical input 
device, handle is, as always, the virtual device's VDI handle. device is the logi- 
cal input device whose mode you wish to check, as follows: one, graphic cursor 
unit (ie. devices that move the mouse pointer); two, value-changing input 
(e.g. shift key, control key, etc.); three, selection input unit (ie., function 
keys); and four, siring input unit (.e., alphabetic keys). Finally, mode is 
returned by vqln_mode: zero indicates request mode, and one indicates sample 
mode. Request mode waits for a particular event to occur on the device before 
the function returns, analogous to the AES event library; whereas sample mode 
simply polls the device and returns, without waiting for an event. 


See Also 
TOS, VDI, vsin_mode 


val_atiributes—VDI function (Iibydi.a/vql_attributes) 
Read the polyline’s current attributes 
include <aesbind.h> 
#include <ydibind.b> 
void vql_attributes(handle, attrib) int handle, attrib; 


val_attributes is a VDI routine that returns the current attributes for the VDI 
polyline routine. handle is the virtual device's VDI handle, The polyline at- 
iributes are written into the array altrib, as Follows: 


aitrib{0] Line type; see the entry for vsl_type for a table of line-type codes. 
aitrib(1] Line color, see the entry for y_opnwk for a table of color codes 


attrib[2] Writing mode: one indicates replace mode; two, transparent mode; 
three, XOR (exclusive or) mode; and four, reverse transparent 
mode. 


aitrib[3) Starting point style: zero indicates square; one, arrowhead; and 1wo, 
rounded, 


attrib[4] Ending point style. 
autrib(5] Line width, 


See Also 
‘TOS, y_pline, VDI, yqf_attributes, vam_sttributes, vat, 


‘qm_attributes—VDI function (libydi.a/vqm_attributes) 
Read the marker’s current attributes 
#include <aesbind.b> 
#include <vdibind.h> 
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void yqm_attributes(handle, attrib) int handle, attritt Sh 


‘yqm_altributes is @ VDI routine that returns the attributes currently set for the 
marker, handle is the virtual device's VDI handle. The marker's attributes are 
written into the array attrib, as follows: 


aurib[0] Marker type, as follows: 


period 

plus sign 

asterisk 

square 

‘diagonal cross 
diamond 
device-dependent 


Some 


airib[1] Marker color. For a table of color codes, see the entry for 
+_opnwk, 

curib[2] Writing mode: one indicates replace mode; two, transparent mode; 
three, XOR (exclusive or) mode; and four, reverse transparent 
mode. 


attrib[3] Marker width. 
cttrib[4] Marker height. 


See Also 
TOS, y_pmarker, VDI, vqf_attributes, vql_attributes, vqt_attributes 


yap_error—VDI function (Itbydi.a/vap_error) 
Inquire if an error occurred with the Polaroid Palette 
#include <aesbind.h> 
#include <vdibind.h> 
Int vap_error(handle) int handle; 
‘The VDI contains s driver for the Polaroid Palette, a camera that can be used to 
shoot slides directly from the Atari ST. vqp_error is a VDI routine that returns 
an error message or user prompt for the camera. handle is the virtual device's 
VDI handle. vqp_error returns one of the following error messag 
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no error 
open dark slide for print film 

‘no port at location specified in driver 

Polaroid Palette not found at specified port 

video cable is disconnected 

operating system does not allow memory allocation 
not enough memory available to allocate buffer 
memory not freed 

driver file not found 

driver file is not of the correct type 

10 user should now process print film 


wear aneunns 


See Also 
‘TOS, VDI, vqp_films, vap_state, vsp_message, ysp_save, ysp_style 


Notes 
This routine uses the VDI's GDOS in its operation. It should not be used if the 
GDOS is not present in your edition of VDI. 


vap_films—VDI function (libydi.a/vap_films) 
Get films supported by driver for Potaroid Palette 
winclude <aesbind.h> 
#include <vdibind.h> 
vold vap_films(handle, names) int handle, names{125}; 


‘The VDI contains a driver for the Polaroid Palette, a camera that can be used to 
shoot slides directly from the Atari ST. vqp_films is a VDI routine that returns 
the names of the fives types of photographic film supported by this driver. 
handle is the virtual device's VDI handle. films is an array that holds the names 
of the films supported. 


See Also 
TOS, VDI, vqp_error, vap_state, vsp_message, vsp_save, vsp_style 
Notes 


This routine uses the VDI's GDOS in its operation. It should not be used if the 
GDOS is not present in your edition of VDI. 


‘yqp_state—VDI function (libvdi.n/vqp_state) 
Read current settings of the Polaroid Palette driver 
#include <aesbind.h> 
#include <vdibind.h> 
yoid yqp_state(handle, &port. &film, &lightness, &imerlace, planes, &indices }; 
int handle, port, film, lightness, interlace, lanes, indices|8\|2); 
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‘The VDI contains s driver for the Polaroid Palette, a camera that can be used to 
shoot slides directly from the Atari ST. vqp_state returns a block of data that 
gives the driver's settings. handle is the virtual device's VDI handle, port is the 
Port to which the camera is connected; zero indicates the First communications 
port. film is the number of the film for which the driver is currently set. 


lightness is the intensity to which the driver is set, from -3 through three. Each 
number in this range is equivalent to one third of an f-stop, counting from 
zero. Therefore, -3 has half the intensity of zero, and three is twice as intense 
as zero. 


interlace indicates whether the image is interlaced or not; zero indicates not it 


terlaced, and one indicates interlaced. Note that an interlaced image requires 
approximately twice the memory of one that is not interlaced. 


planes indicates the number of colors supported, It is set to a code, from one 
through four; one indicates two colors; two, four colors; three, eight colors; and 
four, 16 colors. 

Finally, indices holds two-character codes for the eight color indices stored in 
ADE format, 


See Also 
TOS, VDI, vap_error, vap_films, ysp_message, vsp_save, vsp_style 


Notes 
This routine uses the VDI's GDOS in its operation. It should not be used if the 
GDOS is not present in your edition of VDI. 


vat_attributes—VDI function (libydi.a/yqt_attributes) 


Read the graphic text's current attributes 

#include <aesbind,h> 

include <vdlbind.h> 

void vgt_attributes(handle, attrib) int handle, attrib{ 10}; 


yqt_attributes is a VDI routine that returns the current attributes for the VDI 
graphics text routine. handle is the virtual device's VDI handle. The graphics 
text attributes are written into the array attrib, as follows: 


attrib[0] Character set. 
atirib[1] Text color. For a table of color codes, see the entry for y_opnwk. 
attrib?) Rotation angle, in tenths of 3 degree (i.e., 0 through 3600). 


atirib[3] Horizontal alignment, For a table of alignment codes, see the entry 
for yst_alignment 
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attrib(4} Vertical alignment. 


attrib[5] Writing mode: one indicates replace mode; two, transparent mode; 
three, XOR (exclusive or) mode; and four, reverse transparent 
mode. 


attrib(6} Character width, 
attrib(7] Character height. 
aurib[8] Cell width. 
aurib(9} Cell height. 


See Also 
TOS, ¥_gtext, VDI, vaf_s 


(tributes, vql_attributes, vqm_attributes 


vat_extent—VDI function (Ibvdl.a/vat_exient) 
Calculate a string’s tength 
+#include <aesbind.h> 
include <vdibind.h> 
void vqt_extent(handle, text. siz 


) int handle, sizel8]; char "text; 


vqt_extent is a VDI routine that calculates the Iength of a string. This is 
especially useful when positioning proportionally spaced text on a. virtual 
device. 


handle is the virtual device's VDI handle. text points to the string whose extent 
you wish to calculate, size is an array of eight integers that give the X and Y 
Coordinates of the box that encloses the text, as follows: size[0] and sizel1] give, 
respectively, the X and Y coordinates of the lower left-hand corner; size12) und 
size[3], X and Y coordinates of the lower right-hand corner; sizel4]/and slzel5|, 
upper right-hand corner, and size[6] and size{7], upper left-hand corner. Note 
that the box extends from the top of the tallest capital letters (e.g. ‘M") to the 
bottom of the lowest descenders (e.g.,'j' or 'y'). 


See Also 
TOS, y_gtext, VDI 


vat_fontinfo—VDI function (Jibydi.a/yqt_fontinfo) 
Get information atout special effects for graphics text 
#include <aesbind.h> 
include <vdibind.h> 
vold vqt_fontinfo(handle, firstchar, lastchar, sizes, maxwidth, ad just) 
Int handle, *firsichar, *lasichar, sizes|§], *maxwidth, ad just{3}; 


fontinfo is a VDI routine that returns information about font sizes, 
especially about the extra space taken up by slanted and shadowed characters. 
This extra space is not taken into account by vqt_extent when it calculates the 


Mark Wi 


ims C 543 


vat_name Lexicon 


length of a string, so you may need to obtain this information from vat_fon- 
tinfo when constructing text to be passed to a specialized output device. 

‘The arguments to vat_fontinfo are as follows: handle is the virtual device's VDI 
handle. firstchar points to the first character in the ASCTI table that can be set 
on this device, using the font and special effects that have been set for it; 
Jastchar points to the last character in the ASCII table that can be so set. These 
values, of course, are set by vqt_fontinfo, maxwidth points to the maximum, 
width of a character in the current font, 

sizes points to an array of five integers that are set by yqt_fontinfo, Each 
represents a dimension of the current font, as follows: 


sizes[0] bottom line to baseline 
sizes{1] descent line to baseline 
sizes/2] half line to baseline 
sizes[3] ascent line to baseline 
sizes[4) top line to baseline 


‘These terms are defined in the entry Cor yst_allgament. 


Finally, adjust points to an array of three integers that are set by vqt_foutinfo;, 
each represents a change to the font size represented by the special effects 
being used, as follows: 


ad just{0} increase in character width 
ad just{ 1} left offset 
od just[2] right offset 


The right offset is the amount of space a slanted letter extends beyond the edge 
of its "cell", which is defined as the width of the character measured across the 
bottom, ‘The left offsct is the extm space that must be set to the left of a 
slanted character, so its neighbor to the left does not slant over it. The increase 
in character is the total of the left and right offsets; this is the value you need to 
figure into the value returned by yql_extent to gain the true extent of a string 
that uses special effects 


See Also 
TOS, ¥_gtext, VDI, vqt_extent, vat_name, vst_aligament 


vgt_name—VDI function (libydi.a/yqt_name) 
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Get name and description of graphics text font 

include <aesbind.h> 

#include <vdibind.h> 

int yqt_name(handfe. font, string) int handle, font; char stringl32) 
vqt_name is 2 VDI routine that returns the name and description of a given 
font, handle is the virtual device's VDI handle. fone is the number of the font 
whase name you want. Finally, string is where yqt_name writes the font name 
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and information. The first 16 chars hold the name of the font, and the next 16 
hold a brief description of it 


vgt_name returns the font ID that is needed to access this face with the func- 
tion yst_font. Note that the number of fonts available on a given virtual device 
is returned by the functions y_opawk and y_opnvwk in the variable 
work_out[ 10]. 


Example 

‘The following example prints 3 description of each font currently available to 
the screen device, Note that this example should be compiled with the option 
-VGEM, but that you do not need to run it with the gem command, 


Wirelude <aesbind.h> 
Hinelude <vdibind.hy 


/* global Line A variables used by vi; MIST be included */ 

Int contri 122, intint128), pteintt28}, inteur 128], preour (1261; 
/% arrays Used by v_opwkt 

ine work ing» € 

int work out (8725 


raing) € 
int neshere = 
int vathandl 
int infors2y; 7% array used by vat_name */ 
int 45 7% counter used In f2r() loop */ 
int codes 7* font code returned by vat_nanet) */ 
* open appl ication */ 
‘appl ini tc 
\alhandle =" graf handte(lnowhere, tnamere, nowhere, knovher 
Vopewk(uork_ in, Kedihandte, workout); 
71 ceturn code and description of all ecreen fonts */ 
1 <= work outt1O); 64) ¢ 
code = vat nametvdibandle, §, infor; 
printtcirent tas Kein", cf 
a 
[7 close device, exit */ 
¥elsvak(vainandie) 
appl_exitz 
exittO); 
y 


See Also 
‘TOS, VDI, vst_font 
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vyqt_width—VDI function (libydi.a/vqt_width) 
Get character cell width 
#include <aesbind.h> 
#include <vdibind.h> 
int vat_width(handle, character, &width, &le/t. &right) 
Int handle, width, left, right; char character, 


vgt_width is a VDI routine that returns the width of a given character's cell, 
plus information about the “white space” that surrounds the character; it does 
not take into account the angle at which text is written, or any special effects 
used. Much of the same information is returned by the AES routine 
graf_handle. 


handle is the virtual device’s VDI handle. character is the character whose size 
is to be checked. width is returned by yqt_width; it is the width of the charac~ 
ter's cell, left and right are also set by vqt_width; they indicate the amount of 
wists apes left'ony respacelvely, the IY and the sigh of the ciiazacter withla 
its cell. 


vqt_width returns -1 if the character requested is invalid or otherwise cannot 
be measured. 


See Also 
TOS, vs 


Next, VDI 


¥r_recfl—VDI function (Iibydl.a/vr_reetl) 
Draw & rectangular fill area 
#include <aesbind.h> 
#include <ydibind.h> 
vold vr_reefl(handle, xvarray) int handle. 


wr_recfl is a VDI routine that draws a rectangle. Unlike its cousin y_bar, 
wr_reefl will draw only a rectangular chunk of the preset fill pattern; it cannot 
draw a perimeter, handle is the virtual device's VDI pattern, 


xyarray sets the X and Y coordinates from which to construct the pattern; the 
even-numbered entries indicate the X coordinates, and the odd-numbered 
entries the Y coordinates. Which corner of the rectangle each pair of coor 
dinates indicates will differ depending on whether the virtual device has been 
set to normalized device coordinates (NDC) or to raster coordinates (RC). On 
an NDC device, the first pair points to the lower left-hand corner and the 
second pair to the upper right-hand corner; whereas on an RC device, the first 
pair points to the upper left-hand corner and the second pair to the lower 
right-hand corner, 


Note that to use this routine, the fill type must be set with ysf_interior, the fill 
style by vsf_style, and the fill color by vst_color. 
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Example 

‘This example uses the random-number routines to create 4 random pattern, and 
fills the screen with it, The random-number generator is seeded with the lower 
portion of the system time. Typing any key repeats the process; typing 
<teturn> exits. Note that because the Atari ST bumps the system time in two- 
second increments, you must wait at least two seconds before a new pattern can 
be drawn. 


Binelude <oesbind.t 
Hinelude <gendefs.t 
Wineluge <osbind.he 
Hinelude <vdibind. he 


def ine RETURN Ox1C0 7 scan code returned by return key */ 
define USER 4 7 code for useridetined Hil pattern */ 


7 global Line A variables used by vai; RUST be fneluded */ 
nt contri {12}, intin( 28), ptsin(1281, Intout (128), ptaout (128); 


Jf aeray used by va_elipt) and ve_rectlty */ 
‘int ayarrayD = C1, 1, 659, 397 3; 

7% arrays used by v_opridk() */ 
int work ta © C41, 1 ty t 
Int work out 1573; 


7° array used by vat_udpatt) */ 
ine stb 016)5 


J" throcavay declaration, to keep systen fram scribbling over itt 
{nt nowhere = 0; 


maint) ¢ 
int vaihendie;s 77 virtual device's handle */ 
int keys 


77 0K, here we go 
appl_initoz 
valhandle = graf_handtecenesmere, know 
vopnvk(work_in, Evdibandle, work out 
eliptwdinindte, 1, xyarray); 
v Rlete_e¢udtinareied;| 
VEt_interor(vdihandle, USER); 


doffLl¢vdihandien; 


fortsz) € 
key = evnt_keybdt); 
if they == RETURN) 
v.shou_ctvdthandtey; 
Vietevaecvdthandley; 
neein 
exited: 


wen 


” 


+ Hncabiere, tnownere); 
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> else 
efit (vdihandtey; 


int counter; 


szrond¢Cint Gettimecd): 
for (counter = 0; counter « 16; counterss) 
Fil feounter] = randy; 
vet_udpat(ydihendte, FFU, 195 
vr_recfl(vdihandle, yarrey): 


y 


Sce Also 
TOS, v_bar, VDI 


‘yr_trnfm—VDI function (libydi.a/vr_trafm) 
Transform a raster image 
include <nesbind.h> 
include <gemdefs.h> 
‘include <ydibind.h> 
oid ve_trafm(handle, &sourcem/db, &destmfdb) 
int handle; FDB sourcem/db, destmfdb; 


vr_trnfm is @ VDI routine that transforms a raster image between standard 
(device-independent) and device-dependent forms, handle is the virtual 
Uevice's VDI handle. svurcem/db and destm/db describe the “memory form 
definition block for the source and destination areas. Note that these are bath 
set to the type FDB, which is defined in the header file gemdefs.h, as follows: 


typedef struct fébste 
« 


long te_adde? 
ine 

int 
int 
int 
Ine 


> FOB; 


fd_addr points to the beginning of the raster area in RAM. If this value is set 
to Zero, vro_cpyfm assumes that a virtual device is being used (e.g., the screen), 
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and uses handle to address that device; it also ignores the rest of the FDB struc~ 
ture, which should be set to zeroes. 


‘fd_w and fd_h give, respectively, the width and height of the area being 
copied to or copied from, in pixels. fd_wdwidth gives the width of the area 
being copied to/from, in 16-bit words (Le., divided by 16), and rounded up. 
‘This information is needed internally by the VDI's raster copying routines, 


‘{4_stand indicates whether the material is in device-dependent format or in 
device-independent (standard) format; zero indicates that it is in device-depen~ 
dent format, and non-zero indicates standard format. Obviously, this should 
not be set to the same value in both sourcem/db and fd_nplanes is the number 
of color planes used in the virtual device. The total number of pixels used in 
the image, then, is the image's height in pixels, times its width in pixels, times 
the number of planes. 


Finally, fd_r? through fd_r3 are used by the system for its own purposes: they 
should be set to zero. 


See Also 
TOS, VDL 


yro_epyfm—VDI function (libydi.a/vro_epyfm) 
Copy raster form, opaque 
#include <aesbind.h> 
tinclude <gemdefs.h> 
#include <vdibind.h> 
void vro_ epyfm(handle. logic. xyarray. &sourcem/db, &destmfdb) 
int handle, logic, xyarrayl8}; FDB sourcem{db, destmfdb, 


vto_cpyfm is a VDI routine that copies a portion of a virtual image, pixel by 
pixél, from one location to another. 


handle is the virtual device's VDI handle. logic defines the mode in which the 
area being copied will be drawn. The following table lists the available modes; 
S indicates the source pixel, and D the destination pixel: 
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Clear desti 
S&D 
S&'D 

'S (replace mode) 

{S & D (erase mode) 

D (has no effect) 

S* D/(exclusive-or mode) 
S| D (transparent mode) 
8 & D) 


werannunne 


14S & D) 
1 (black out destination area) 


Note that setting logic to 6 (ie., to exclusive-or mode) allows you to use 
‘yro_epytm to mimic a hardware sprite, to move images around the screen with 
minimal fuss. 


xyarray defines the area to be copied from and the area to be copied to, xyar= 
ray{01 through xyarray{3} is the area being copied from; the first two numbers 
define the X and Y coordinates of one corner of the rectangle, and the second, 
two define the corner opposite it. Note that if the virtual device is defined as. 

ing normalized device coordinates (NDC), the first corner is the lower left- 
hand corner and the second the upper right-hand corner, whereas if the device: 
‘uses raster coordinates (RC), the first corner is the upper left-hand corner and 
the second is the lower right-hand corner. xyarray{4] through xyarray{7} 
define the destination rectangle, in the same manner as the source rectangle. 
Note that for predictable results, the source and destination rectangles should be 
of the same size. 


Finally, sourcem/db and destmfdb describe the “memory form definition 


block” for the source and destination areas, Note that these are both set to the 
type FDB, which is defined in the header file gemdefs.h, as follows: 
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typedef struct fabstr 
« 


‘{a_addr points to the beginning of the raster area in RAM. If this value is set 
to Zero, vro_epyfm assumes that a virtual device is being used (e.g., the screen), 
‘and uses handle to address that device; it also ignores the rest of the FDB struc~ 
ture, which should be set to zeroes. 


fd_w and: fd_h give, respectively, the the width and height of the area being 
copied to or copied from, in pixels, fd_wdwidth gives the width of the area 
being copied to/from, in 16-bit words (Te., divided by 16), and rounded up, 
This information is needed internally by the VDI's raster copying routines, 


fd_stand indicates whether the material is in device-dependent format or in 
device-independent (standard) format; zero indicates that it is in device-depen- 
dent format, and non-zero indicates standard format. Obviously, this should 
not be set to the same value in both sourcem/db and fa_nplanes is the number 
of color planes used in the virtual device. The total number of pixels used in 
the image, then, is the image's height in pixels, time: th in pixels, times 
the number of planes. 


Finally, fd_r1 through fd_r3 are used by the system for its own purposes; they 
should be set to zero, 


Example 

‘The following examples allows the user to copy one portion of the screen to 
another. When he clicks the mouse the first time, he draws a rectangle on the 
screen; clicking the mouse again lets him drag the rectangle to another part of 
the screen, When the mouse button is lifted the second time, the contents of the 
rectangle are copied to where the rectangle stopped. Pressing the *W" key chan 
Bes the writing mode, and pressing <return> exits 

Hinclude <gendefs.b> 

finclude <eesbind.n> 

Finelude <vdibind.n> 


yro_cpyfm Lexicon. 


‘idefine RETURN Ox1Ct0 (71 scan cade returned by return key */ 

fidet ine WREY Ox1177 77 sean code returned by W key */ 

define DOW 1 7 mouse button is down */ 

define CLICKS 1 7° na. of clicks expected on mouse button */ 
define BUTTON 1 7 sevich button; 1 leftmost */ 

define HOLLOW 0 (7 make #111 type hollow #7 

define FULT 4 72 FULL Te user-defined type (default, fuji) #7 
‘define REPLACE 1 (7 make writing mode REPLACE */ 

def ine X0R 3 77 wake writing mode YOR */ 


/* global Line A varfables used by vil: MUST be included */ 
int contel (12), intint 128], ptsintt28, intoutt128}, ptsoutt'28) 
n 

* array used by vs.clip(); MUST be set, or images that extend 
* beyond the screen perimeters will write over lov-Level mesary 
Coupe, RAM dinks, spoolers, ete.) 

Ri 

int cliparraya) = C1, 1, 639, 399 9; 

1* arrays used by ¥-opwk() */ 

ine work ind = € 1, 1%, 1, 3, 
int workout (5 
7 areay used by v.bart) */ 

Int xyarray() * ( 120, 100, $20, 300 >; 

(0 arceys used by vro_cpyin() */ 

int copyarray (8; 

7 throu-avay declarations, to Keep systen from scribbling over itself */ 
{nt newhere = 0; 

Rect norect * (0, 9, 0, 9 9; 


maint ¢ 
7* declarations used by ent aultico *7 
int selection; 7 code tor event that occurred */ 
nwigned int which = (KEYED | MU BUTTON); 
int buffer(113; 7? place to write AES messages */ 
scan code of key pressed by user */ 
7+ mouse X coordinate */ 
77 mouse ¥ coordinate */ 


7 virtual device's handle */ 
int Logie = 3; 77 used to cycle through Logie types */ 
FB holder CO, 0, 0, 0, 0, 0, 8, 0,09; 

7? used by vro_cpvim: all zeros here */ 
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1 06, here ve 90 
eppl_inito; 
‘graf mouse ARROW, Lrewhere); 
vdihandle = graf handle(Enohere, Snoshere, Enewhere, tnovhere); 
vioprvwk(work_in, Avdihandle, work_out); 
vaclip(vdinendie, 1, eliparray); 
vef_interfortwdihandle, FUND; 
vst perimeter(vdihandle, 19; 
grai_nouse(HOFF, Enownere); 
vbertvdihardle, yarray)s 
GFaf_nouse HOM, Knowhere); 


« 
Selection = evnt_multi(abich, CLICKS, BUTTON, DOWN, 
D, nerect, 0, nerect, buffer, 0, 0, dnousex, Brousey, 
nowhere, Knoshere, tkey, nowhere); 
suitedtselection ¢ 


cease MU_KEYED: 
Ff key == RETUREY ¢ 
‘Vcluvak(vdthandl ed; 
split; 
exit@o); 


4 


fort 


‘ 
Mf (hey == WLKEY) 
Loalesss 
break; 
‘coe MU BUTTON: 
Weterreytvdthandie, meusex, mousey 
vbertvdihardle, xyarray} 
\Viur_sode(vdihandle, REPLACE 
‘grat_nouse(\OFF, Inowhere) 
‘vro_epyte(vaihandle, (Logick16), copyarray, 
holder, thelderd; 
grat _nouse(H OM, krowbere); 
break: 
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etarray(hendle, meusex, mousey? 
int handle, mouser, mousey; 
c 


/* set source rectongle's coordinates */ 
‘copyarrey{O) = xyarray{0} = meusex; 

copyarrayt8 = xyarcayt%} = mousey: 

raf _rubbextnousex, mousey, 0, 0, width, Rheight); 
copyarray(2l = xyarrayi2) = (aousex + width} 
‘copyarreyiS) * xyarray(5} = (mourey + height); 


/* Now draw 2 rectangle around source ares */ 

‘grat_mouse(H OFF, nowhere); 

yswr_nodethordle, x08); 

vat_interforthandte, HOLLOW); 

vbarthondie, xyarray): 

Brat_nouse<M'ON, Enownere); 

walt for second button event; then set coordinates 

* tor destination rectangle. 

” 

‘emmt_button(CLICKS, BUTTON, DOW, Enowhere, nowhere, 
Enowtere, Enowmere); 

raf_dragboxtwidth, height, moukex, mousey, 
0, 0, 639, 399, knewe, knewy)z 

copyarrayté) * news: 

copyarray(S) = nexy: 

copyarraytel = <newk + wiath); 

copyarray(7) = (newy + height); 

return; 


> 


See Also 
TOS, VDI, vrt_epyfm 


yrq_choice—VDI function (libydi.a/vrq_choice) 
Return status of function keys when any key is pressed 
#include <aesbind.h> 
include <ydibind.h> 
vold yrq_choice(handle, in, @out) int handle, in, out; 


vrq_choice is a VDI routine that returns the status of the function keys when’ 
any key is pressed. In VDI jaragon, it operates the select device in request 
‘mode; these terms are described more fully in the entry for vsin_mode. 
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handle is the virtual device's VDI handle. in is the number of the function key 
you want to check, one through ten. The function terminates when any key is 
pressed; if the key was @ function key, out holds its number; if another key was 
struck, ow holds its ASCII value. 

See Also 

TOS, VDI, vsm_choice 


Noles 
Before this function can be used, the function vsin_mode(handle, 3, 1) must be 
entered, which will place the valuator device into request mode. 


+tq_locator—VDI function (libydl.a/vrq_locator) 


Find location of mouse cursor when a key is pressed 
#include <aesbind.h> 

#include <vdibind.h> 

yoid vra_loeator(handle, xcoord, yeoord, &xout, &yout, &key) 
int handle, xcoord, yeoord, xout, yout, key; 


yrq_locator is a VDI routine that returns the location of the mouse cursor when 
mouse button is pressed. In VDI jargon, it operates the position input devices 
in request mode; these terms are described more fully in the entry for 
ysin_mode, 


handle is the virtual device's VDI handle. xcoord and ycoord are, respectively, 
the X and Y coordinates of the mouse pointer’s initialized position, 


xout and yout are, respectively, the X and Y coordinates of the mouse pointer 
when a key is pressed. Finally, the low byte of key gives the ASCII code of the 
key that was pressed to terminate the polling of the screen, The left and right 
buttons on the mouse can also terminate polling; these return, respectively, 0x20 
and 0x21, Note that because any key can end polling of the screen, the 
Programmer must write a loop if he wants to terminate on a particular key. 


See Also 
TOS, VDI 
Notes 


Before this function can be used, the function vsin_mode(handie, 1, 1) must be 
entered, which will place the locator device into request mode. 


yrq_string—VDI function (Iibydi.a/veq_string) 


Read a string from the keyboard 

include <aesbind.h> 

#include <vdibind.h> 

void vrq_string(handle, length, echo, xyarray, string) 
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int handle, length, echo, xyarray{2}; char *string; 


yrq_string is 2 VDI routine that reads a string from the keyboard. The string is 
automatically terminated with a NUL character. The systems stops accepting 
characters either when the user presses the <return> key, or when the string ex- 
ceeds the maximum length set by the user. In VDI jaragon, it operates the 
string device in request mode; these terms are described more fully in the entry 
for vsin_mode. 


handle is, as always, the virtual device's VDI handle. length is the maximum 
length of the string, in characters. echo indicates whether or not you want the 
string echoed to the screen as the user types; zero indicates no echo, whereas 
one indicates to echo, xyarray gives the X and Y coordinates of where on the 
screen to begin echoing the string. Finally, string points to where the string 
will be written. 


See Also 
‘TOS, VDI, vsm_string 
Notes 


Before this Function can be used, the function ysin_mode(handle, 4, 1) must be 
entered, which will place the valuator device into request mode. 


yrq_yaluator—VDI function (libydi.a/vrq_valuator) 
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Return status of shift and cursor keys 

#include <aesbind,h> 

#include <ydibind.h> 

void yeq_valeator(handle, in, out, Akey) lat handle, in out, Key 


yeq_valuator is s VDI routine that returns the status of the valuator keys. In 
VDT jargon, it operates the valuator keys in request mode; these terms are 
described more fully in the entry for vsin_mode. 


handle is the virtual device's VDI handle, in is the code of the valuator key 
whose status you wish to check. Key is the code of the key that was pressed to 
terminate this function, Finally, ow is the value of key plus a specific value 
that indicates which valuator key was pressed along with it, as follows: 


Cursor up key plus ten 
Cursor down key minus ten 
Shift/cursorup key plus one 
Shift/cursor down key minus one 

See Also 


TOS, VDI, vsm_yaluator 
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Notes 
Before this function can be used, the function vsin_mode(handle, 2, 1) must be 
entered, which will place the valuator device into request mode. 


yrt_epyfm—VDI function (libydi.a/vrt_epyfm) 


Copy raster form, transparent 

#include <aesbind.h> 

#include <gemdefs.h> 

include <ydibind.h> 

void vrt_cpyfm(handle, mode, xyarray, &sourcemfdb. &destmfdb, color) 
int handle, mode, xyarray18], color; FDB sourcem fab, destmfab, 


yet_cpyfm is a VDI routine that copies a monochromatic image onto a 
polychromatic device, such as the screen. It resembles the blitting function, 
vro_cpyfm, but it is designed particularly for moving images around the screen 


handle is the virtual device's VDI handle, mode is the mode in which the image 
is written, as follows; one, replace mode; two, transparent mode; three, XOR 
(exclusive or); and four, reverse transparent. Note that these are the same codes 
used by the VDI routine vswe_mode, which is usually used to set the writing 
mode, 


xyarray defines the area to be copied from and the area to be copied to, xyar- 
ray{0} through xyarray{3] is the area being copied from; the first two numbers 
define the X and Y coordinates of one corner of the rectangle, and the second 
two define the corner opposite it. Note that if the virtual device is defined as 
using normalized device coordinates (NDC), the first corner is the lower left- 
hand corner and the second the upper right-hand corner, whereas if the device 
uses raster coordinates (RC), the first corner is the upper left-hand corner and 
the second is the lower right-hand corner. xyarray{4] through ayarrayl7] 
define the destination rectangle, in the same manner as the source rectangle. 
Note that for predictable results, the source and destination rectangles should be 
of the same size. 


sourcemfdb and destmfdb describe the “memory form definition block for the 
source and destination areas. Note that these are both set to the type FDB, 
Which is defined in the header file gemdefs.h, as follows: 


387 


ys_clip Lexicon 


typedet struct fabstr 

€ 
long #6 adie; 
int 
int fh; 
int fd scien; 
int fd_stond 
int fdinptanes: 
ine fori; 
int fre 
int £6003; 

> Foy 


{d_addr points to the beginning of the raster area in RAM. If this value is set 
to Zero, v#t_epyfm assumes that a virtual device is being used (e.g., the screen), 
and uses handle to address that device; it also ignores the rest of the FDB struc- 
ture, which should be set to zeroes. 


‘Jd_w and fd_h give, respectively, the the width and height of the area being 
copied to or copied from, in pixels. /d_wdwidth gives the width of the area 
being copied to/from, in 16-bit words (Te., divided by 16), and rounded up. 
‘This information is needed internally by the VDI's raster copying routines. 


fd_stand indicates whether the material is in device-dependent format or in 
deVice-independent (standard) format; zero indicates that it is in device-depen~ 
dent format, and non-zero indicates standard format. Obviously, this should, 
not be set to the same value in both sourcemfdb and fd_nplanes is the number 
of color planes used in the virtual device. The total number of pixels used in 
the image, then, is the image's height in pixels, times its width in pixels, times 
the number of planes. 


Finally, fd_r? through fd_r# are used by the system for its own purposes: they 
should be sét to zero. 

See Also 

TOS, VDI, vro_epyfm 


¥s_clip—VDI function (libydi.s/vs_clip) 
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Set the virtual device's clippi 
#include <aesbind.h> 
#include <ydibind.h> 
void ys_clip(handie, flag, xyarray) int handle, flag. xyarray\4| 


VDI routine that sets the clipping rectangle for a virtual device. 


rectangle 
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handle is the virtual device's VDI handle, flag indicates whether clipping 
should be turned on or off: zero indicates off, one indicates on. 
Finally, xyarray is an array of four integers that place the clipping rectangle, as 
follows: 

xyarray[0] X coordinate of first corner 

xyarray[1] ¥ coordinate of first corner 

xyarray[2] X coordinate of opposite corner 

xyarray['3] Y coordinate of opposite corner 


Note that if the device is set to normalized device coordinates (NDC), the first 
corner is the upper left-hand corner of the image; whereas if the device is set to 
raster coordinates, the first corner is the lower left-hand corner. 


Example 
For an example of this routine, see the entry for y_pline, 


See Also 
Tos, VDI 


¥s_color—VDI function (libydi.a/vs_color) 
Set color intensity 
winclude <aesbind.h> 
#include <ydibind.h> 
vold ys_color(handle, index. rgbarray) int handle, index, rgbarrayi3h; 


ys_color is a VDI routine that sets the intensity of a color. Each color is set by 
adjusting the intensity of three electron guns, one for red pixels, another for 
green pixels, and a third for blue. vs_color allows you to adjust the intensity of 
each gun for given color. 


handle is a virtual device's VDI handle. index is the code for the color being 
adjusted; for a table of these indices, see the entry for y_opnwk. Finally, rehar- 
ray[0] through rgbarray/ 2] hold, respectively, the new value for the red, blue, 
and green guns; each value is an integer between one and 1,000. 

See Also 

TOS, VDI 


¥5_curaddress—VDIfunction (libydi.a/vs_curaddress) 
Move alphabetic cursor to specified row and column 
#include <aesbiad.h> 
#include <ydibind.h> 
void vs_curaddress(handle, row, column) int handle, row, column; 
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vs_curaddress is 2 VDI routine that moves the alphabetic cursor to a specified 
row and column on the virtual device. Note that to use this routine, the virtual 
device must first be placed in alphabetic mode, with the routine y_enter_cur. 
handle is the virtual device's VDI handle. row and column give, respectively, 
the row and column where you wish to position the alphabetic cursor. 


See Also 
TOS, VDI, vq_curaddress 


ys_palette—VDI function (libydi.a/vs_palette) 
Select color palette on medium-resolution screen 
#include <aesbind.h> 
#include <rdibind.h> 
void vs_palette(handle, palette) int handle, palette; 


¥s_palette is a VDI routine that selects a palette for use on the medium-resolu~ 
tion screen, handle is the virtual device's VDI handle. palette is @ pre-set color 
palette: zero (the default) indicates a palette of red, green, and brown; and one 
indicates a palette of cyan, magenta, and white. 


See Also 
TOS, VDI 


vse_form—VDI function (libydi.a/yse_form) 
Draw a new shape for the mouse pointer 
‘include <aesbind.h> 
include <vdibind.h> 
void vse_farm(handle, form) int handle, formi37k; 


yse_form is a VDI routine that draws a new shape for the mouse pointer, 
handle is the virtual device's VDI handle, 


form is an array of 37 integers. form[0] and form/1] give, respectively, the X 
and Y coordinates for the “action point”, or the point on the pointer that is 
considered significant; in most instances, this is the upper left-hand corner. 
‘These values are set relative to the upper left-hand corner. 


form[2] is reserved by the VDI, and must be set to one. form/3) is the color 
index mask, and is normally set to zero. form/4] is the color index cursor 
form, and is normally set to one. form/5] through form/ 20] gives the bit form 
of the mouse pointer’s mask, or its monochromatic image. Finally, form/21] 
through form/36) gives the cursor form in color, bits set to one in this map are 
shown in the bickground color. 


Note that once the new shape is loaded with yse_form, it can be called with 
graf_mouse(handle, 285, form); or a similar call. 
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See Also 
TOS, VDI 


vsf_color—VDI function (Iibydi.a/vsf_color) 
Set a polygon's fill color 
#include <aesbind.h> 
#include <rdibind.h> 
void vsf_color(handie, color) int handle, color; 
vsf_color is a VDI routine that sets a polygon’s fill color. handle is the virtual 
device's VDI handle. color is the color to which the polygon’s fill should be set; 
for a table of color settings, see the entry for v_opnwk. Note that this routine 
can be used only with ysf_Interior and vst_style. 
See Also 
TOS, ¥_1 


y_opnwk, VDI, ysf_interior, vsf_style 


ysf_interior—VDI function (libydi.a/ysf_interior) 
Set a polygon's fill type 
include <aesbind.h> 
#include <vdibind.h> 
void vsf_interior(handle, type) int handle, type; 


vsf_interior is @ VDI routine that lets you choose what type of filling will be 
used for a polygon, Aandle is the virtual device's VDI handle. type is the type 
of fill you choose, as follows: 


empty (same as background) 
solid 

Patterned 

cross-hatched 

user-defined type 


Using the “empty" setting and having the “transparent” flag set by the routine 
yewr_mode will result in only the outline of a polygon being drawn, with what 
ig in the background filling its interior. 


Example 
For an example of this routine, see the entry for y_bar. 


See Also 
TOS, y_bar, VDI, vsf_style 


vsf_perimeter—VDI function (Iibydi.a/rsf_perimeter) 
Set whether to draw a perimeter around a polygon 
#include <aesbind.h> 
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vsf_style—VDI function (Iibydi.a/vsf_style) 
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#include <ydibind.h> 
void vsf_perimeter(handle, flag) int handle, flag; 


vsf_perimeter is a VDI routine that lets you choose whether or not to draw a. 
perimeter around a polygon you are creating. The perimeter is in the color that 
you have set with the routine ysf_color, and it is always one raster wide, 
handle is the virtual device's VDI handle. flag indicates whether or not to draw 
{ perimeter: zero indicates not to draw a perimeter, and one indicates to draw. 
one. 

Example 

For an example of this routine, see the entry for y_bar. 


See Also 
TOS, y_bar, VDI, vsf_color 


Set a polygon’s fill style 

winclude <aesbind.h> 

include <vdibind,h> 

void vsf_style(handle, style) int handle, style; 


A polygon’s fill type is set with the routine vsf_interior, and can be one of the 
Following: hollow, solid, patterned, cross-hatched, or user defined, If one of 
the last three types is selected, then ysf_style can be used to selected the style 
of filling, 


handle is the virtual device's VDI handle. style is the code number of the fill 
style selected. For a patterned fill, 24 styles are available, as follows; 
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1-8 gray tones, from lightest (1) to solid (8) 

9 horizontal “brick” pattern 

10 disgnonal “brick” pattern 

11 inverted ‘v's 

12 arch 

13 cross-hatched line segments 

14 heavy random dots 

1S light random dots 

16 interwoven hollow lines 

17 zig~zagged thin lines plus dots 

18 horizontal and vertical lines of dots 
19 black balls in checkerboard pattern 

20 overlapping scale shapes 

21 overlapping diagonal rectangles 

22 rectangles in checkboard pattern 

23. diamond pattern 

24 ines in herringbone pattern 


For a cross-hatched fill, 12 styles are available, as follows: 


1 tight, closely spaced diagonal lines 

2 heavy, closely spaced diagonal lines 

3 heavy, closely spaced, diagonal cross-hatched lines 

4 closely spaced vertical lines 

S closely spaced horizontal lines 

6 heavy, closely spaced, perpendicular cross-hatched lines 
7 light, widely spaced diagonal lines 
8 
9 
10 
11 
12 


heavy, widely spaced diagonal lines 
light, closely spaced, diagonal cross-hatched lines 
widely spaced vertical lines 

widely spaced horizontal lines 

widely spaced perpendicular lines 


‘The styles for 2 user-defined fill are set with the function ysf_udpat, The 
default user-defined fill is the “fuji" (the Atari symbol), 


Example 
For an example of this routine, see the entry for y_bar, 


See Also 
TOS, v_bar, VDI, vsf_interior 
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vsf_udpat 


VDI function (libydi.a/ysf_udpat) 
Define a fill pattern 

#include <aesbind.h> 
¥include <vdibind.h> 
void vsf_udpat(handle, pattern. planes) Int handle. pattern|n}, planes; 


ysf_udpat is a VDI routine that allows a user to define a customized fill pattern, 
handle is the virtual device's VDI handle. planes is the number of color planes 
used in the pattern; the fill pattern must have a 16-integer array for each color 
plane. patter is an array of 16 integers that defines the dot pattern, besinning 
in the upper left-hand corner and working through the lower right-han 
corner, 7 must be set to 16 times planes, Note that once a pattern has been set, 
it must be loaded using vsf_interior and vsf_style. 


Example 
For an example of this function, see the entry for vr_recfl. 


See Also 
TOS, y_bar, VDI, vsf_laterior, vsf_style 


Set input mode for logical input device 

#include <aesbind.h> 

#include <vdibind.h> 

int ysin_mode(handle, device, mode) int handle, device, mode; 


ysin_mode is a VDI routine that sets the input mode for a giyen logical input 
device, This mode is used by a set of functions that poll the input devices for 
information about their current status. 


The VDI recognizes four types of input devices: Position input deviecs control 
the position of the mouse cursor on the screen; these are the mouse itself or the 
cursor keys. Value-changing devices affect only the value returned by another 

put device; these include the shift key, the control key, and the alt key 
Selection input devices return a selection number; these refer only to the Atari 
ST's function keys. Finally, siring input devices are the alphabetic keys on the 
Atari ST's keyboard, by which strings are input. 


handte is the virtual device's VDI handle. device indicates the logical device” 


you wish to set: one indicates the position devices; two, value-changing input 
devices; three, the selection devices; and four, the string-input devices, 


Finally, mode is the mode to which you want to set the device. Request mode 
tells the polling function to wait for input from a given device, e.g., for a key. 
to be struck or a mouse button to be pressed. Sample mode simply polls th 
device and returns, without waiting for an event, One indicates request mode, 
and two indicates sample mode. 


vysin_mode returns the mode to which the device was set. 


Lexicon vsl_color-vsl_type 


See Also 
TOS, VDI, vain_mode, vrq_choice, vrq_locator, vrq_string, vrq_valuator, 
ysm_cholce, ysm_locator, vsmi_string, ysm_valuator 


4sl_eolor—VDI function (libvdl.a/yst_color) 
Set a line's color 
#include <aesbind.h> 
include <vdibind.h> 
int vsl_color(fiandle, color) int handle, color; 


vsl_color is 2 VDI routine that sets the color of a line, handle is the virtual 
device's VDI handle, color is the color to which the line is being set. For a list 
of the available values, see the entry for y_opnwk. If the color requested is not 
available on the target virtual device, the line color will be set to one (black). 


vsl_color returns the color to which the line was set. 


See Also 
TOS, VDI, v_pline 


sl_ends—VDI function (libydi.a/ysl_ends) 
Attach ends to 2 line 
#include <aesbind.h> 
#include <ydibind.h> 
void ysl_ends(handle, beginning, end) int handle, beginning. end 
ysl_ends is a VDI routine that attaches ends to a line. handle is the virtual 
device's VDI handle, beginning and end refer to the type of Figure drawn at, 
respectively, the beginning and the end of the line, as follows: 


0 squared end (default) 
1 arrowhead 
2 rounded end 


Example 
For an example of this routine, see the entry for y_pline, 


See Also 
TOS, VDI, v_pline 


vsl_type—VDI function (libvdi.a/vsl_type) 
Set a line's type 
#include <aesbind.h> 
#include <vdibind.h> 
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ysl_udsty—VDI function (libydi.a/vsl_udsty) 


ysl_width—VDI function (libydi.a/ysl_width) 
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int vsl_type(handle, type) int handle, type: 


ysl_type is a VDI routine that sets a line's type. handle is the virtual device's 
‘YDI handle, 

type is the type to which the line is being set, as follows: 
solid 

long dashes 

dots 

dash-dot 

dashes 

dash-dot-dot 

user-defined 

8-n device-dependent 


Mowe 


vsl_type returns the type to which the line was set. 


Example 

For an example of this routine, see the entry for »_pline. 
See Also 

TOS, v_pline, VDI, ysl_udsty 


Set user-defined line type 

+#include <aesbind.h> 

‘include <vdibind.h> 

void ysl_udsty(Aand/e, pattern) int handle, pattern; 
ysl_udsty is a VDI routine that lets the user design a line type to be drawn by 
¥_pline. handle is the virtual device’s VDI handle. pattern is a bit map for the 
pattern to be drawn, Setting a bit to one means that its 1/16 portion of a ling 
unit will be drawn; setting it to 2ero means that its portion will be blank. 
Note that once the bit pattern is set with vsl_udsty, it must be loaded with the 
function yst_type. 

See Also 

TOS, y_pline, VDI, vsl_type 


Set a line’s width 

include <aesbind.h> 

#include <vdibind.h> 

int vsl_width(handle, width) int handle, width; 
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yel_width is a VDI routine that sets a line's width. handle is the virtual device's 
VDI handle. 


width is the width of the line to be drawn; this will vary depending on whether 
the virtual device being drawn on is set in normalized device coordinates (NDC) 
or raster coordinates (RC), The value work_out{7] indicates how many line 
widths ‘are available for you to use on that device; see the entry for y_opnwk 
for more information. If the line width you request is not available on the vir- 
tual device, the line width will be set to the next smaller width, 

ysl_width returns the width to which the line was actually set. 


Example 

For an example of this routine, see the entry for v_pline. 
See Also 

TOS, VDI, y_opnwk, y_pline 


ysm_cholee—VDI function (Ilbydl.a/rsm_choice) 
Return last function key pressed 
include <aesbind.h> 
#include <vdibind.h> 
Int ysm_cholee(handle, &key) Int handle, key; 


vsm_choice is a VDI routine that returns the last function key pressed, whether 
or not another key is pressed. To use VDI jargon, it operates the valuator 
device in sample mode; these terms are explained more fully in the entry for 
ysin_mode, handle is the virtual device's VDI handle, choice, which is set by 
ysm_choice, is the number of the function key last pressed, from one to ten. If 
no function key was pressed, the ASCII code of the last key pressed is returned. 


ysm_choice returns either zero or one; the former indicates that no key was 
pressed, whereas the latter indicates that a key was pressed. 

See Also 

TOS, VDI, yrq_choice 

Notes 


Before this function can be used, the function ysin_mode(handle, 3, 2) must be 
entered, which will place the locator device into sample mode, 


‘ysm_color—VDI function (libydi.a/vsm_color) 
Set a marker's color 
include <aesbind.h> 
winclude <vdibindh> 
int vsm_colorthardle. color) int handle, color, 
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vam_color is a VDI routine that sets 2 marker's color. handle is the virtual 
device's VDI handle. color is the color you select for the marker; for a list of 

color codes, see the entry for y_opnwk. If the color you requested is 
ilable, the marker's color will be set by default to one (black). 


ysm__color returns the color to which marker is actually set, 


See Also 
‘TOS, VDI, y_pmarker 


ysm_height—VDI function (libydi.a/vsm_height) 


ysm_locator—VDI function (libvdt. 
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Size a marker 

include <aesbind.b> 

ainclude <ydibind.h> 

Int vsm_height(handle, height) int handle, height; 


ysm_height is a VDI routine that sizes a marker. handfe is the virtual device's 
vprhandle. 


height is new size of the image, in Y coordinate units; these are used to avoid 
problems with scaling. Note that not every device will support every requested 
size of marker, Interrogating the variable work_out/9), which is a member of 
the array returned by the routine used to open the virtual device, will indicate 
the number of marker sizes available; zero indicates continuous scaling, i.e., that 
every size is supported, See the entry for »_opnwk for more information. Note 
that if a particular size is unavailable, the marker will be rescaled automatically 
to the next available smaller size, 


vém_height returns the height to which the marker is set. 


Example 
For an example of this routine, see the entry for y_circle. 


See Also 
TOS, VDI, v_opnwk, y_pmarker 


./ysm_locator) 

Return mouse pointer's position 

include <aesbind.h> 

#include <vdibind.b> 

int vsm_locator(handle, xcoord. yeoord, &xou. yout, &key) 
int handle, xcoord, ycoord, xout. yout, key; 


ysm_locator is a VDI routine that returns the mouse pointer's position whether 
or mot a key was pressed. To use VDI jargon, it operates the position input 
device in sample mode; these terms ere explained more fully in the entry for 
ysin_mode. Because VDI programs work by interrupts, a program does not 
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know where the mouse pointer is at any given point; this function is handed an 
initial set of coordinates for the mouse pointer, then polls the screen to find 
where it is now. It returns and indicates whether the pointer has changed from 
the initializing coordinates, whether a key was pressed, or both; and it sets 
values for the new X and Y coordinates (if any) and for the key that was 
pressed (if any). 


handle is, as always, the virtual device's VDI handle. xcoord and ycoord give, 
respectively, the X and Y coordinates of the mouse pointer’s initialized position; 
these may be set by another function. 


xout and yout are set by vsm_locator; they give, respectively, the mouse poin- 
ter’s X and Y coordinates, if they are different from the initializing coor- 
dinates, Key is also set by ysm_locator, its low byte gives the ASCIT value of a 
key pressed in the interval, if any. 


Finally, rsm_locator returns a code, from zero to three, which indicates the 
following: zero, the mouse pointer was not moved and no key was pressed; onc, 
the mouse pointer was moved, but no key was pressed; two, the mouse pointer 
‘was not moved, but a key was pressed; and three, the mouse pointer moved and 
a key was pressed. 


See Also. 
TOS, VDI, vrq_locator 


Notes 
Before this function can be used, the function ysin_mode(handle, 1, 2) must be 
entered, which will place the locator device into sample mode. 


ysm_string—VDI function (libvdi.n/vsm_string) 
‘Kead a string from the keyboard 
#include <aesbind.h> 
#include <vdibind-h> 
Int ysm_string(handle, length, echo, xyarray, string) 
int handle, length, echo, xyarray(2}; char *string; 


‘ysm_string is a VDI routine that reads a string from the keyboard. The string is 
automatically terminated with a NUL character. Unlike vrq_string, it also 
notes if any non-alphabetic keys were struck. String entry ends either when a 
non-alphabetic key is struck, or when the string exceeds the maximum length 
set by the user. 


handle is the virtual device's VDI handle. length is the maximum length of the 
string. echo indicates whether or not you want the characters echoed to the 
sereen as they are input: zero indicates not to echo, and one indicates to echo. 
ayarray gives the X and Y coordinates of the position on the screen where 10 
begin echoing the string. Finally, string points to the area where the string will 
bbe written; be sure to set aside at least length amount of space for the string, or 
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yom. 


‘ysm_yaluator—VDI function (Iibydi.a/ysm_yaluator) 
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|_type—VDI function (libvdi.a/vsm_type) 


you may write over vital memory. 

vsm_string returns zero if the string was terminated by a non-alphabetic key, 
and’ number greater than one if it was not. If you plan to have the user ter~ 
minate the string with the <return> key, use veq_string instead of the present 
function. 

See Also 

TOS, VDI, vrq_string 

Notes 

Before this function can be used, the function ysin_mode(handle, 4, 2) must be 
entered, which will place the locator device into sample mode. 


Set VDI marker type 
#include <aesbind.h> 
ttinclude <vdibind.h> 
int ysm_type(handte, type) int handle, type; 


ysm_type is a VDI routine that sets the type of marker displayed on the virtual 
device, handle is the virtual device's VDI handle. type is the type of marker 
‘being shown, as follows: 

dot 

plus sign 

asterisk 

square 

diagonal cross 

mond. 

device-dependent 

If the type of marker requested is not available on the virtual device, the 


default marker (an asterisk) will be used. vsm_type returns the type of marker 
to be displayed. 


Example 
For an example of this routine, see the entry for y_eirele. 
See Also 

TOS, VDI, v_pmarker 


Sawer 


Return shift/cursor key status 

include <aesbind.h> 

include <vdibind.h> 

void ysm_valuator(handle, in. &out, dhey, &status) 
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int handle, in, out, Key, status; 


ysm_yaluator is a VDI routine that that returns the status of a shift key or cur~ 
sor Rey whether or not another key is pressed. To use VDI jargon, it operates 
the valuator device in sample mode; these terms are explained more fully in the 
entry for ysim_mode, 


handle is the virtual device's VDI handle, ix is the code of the valuator key 
whose status you wish to examine. Key is set by vsm_valuator, it is the code of 
the key pressed before this routine exits, if any. Because all functions in 
sample mode merely examine the status of a device and return without being 
triggered by a hardware event, a key may not necessarily have been pressed 
during this function's operation. out is the value of key, plus a value that in- 
dicates the status of one or more valuator keys, as follows: 


Cursor up key plus ten 
Cursor down, key 
Shift/cursor up key plus one 
Shift/eursor down key minus one 


Finally, status gives the status of the valuator devices, as follows: 
0 no action occurred 
1 value was changed 
2 key was pressed 

See Also 

‘TOS, VDI, vrq_yaluator 

Notes 


Before this function can be used, the function ysin_mode(hand/e, 2, 2) must be 
entered, which will place the locator device into sample mode. 


vsp_message—VDI function (libydi.a/ysp_message) 
Suppress messages from Polaroid Palette device 
#include <aesbind.h> 
include <ydibind.h> 
void vsp_message( handle) int handle; 


ysp_message is a VDI routine that suppresses messages from the Polaroid Palette 
device. These messages are normally output to the screen. handle is the virtual 
device's VDI handle. 


See Also 
TOS, VDI, vap_error 
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Notes 
‘This routine uses the VDI’s GDOS in its operation. It should not be used if the 
GDOS is not present in your edition of VDI. 


vsp_saye—VDI function (Iibydi.a/vsp_save) 


‘Save to disk current setting of Polaroid Palette driver 

include <aesbind.h> 

#include <vdibind.h> 

void ysp_save(hardle) int handles 

‘The VDI contains a driver for the Polaroid Palette, a camera that can be used to 
shoot slides directly from the Atari ST. ysp_save is a VDT routine that writes 
the current settings for this driver to disk. Randle is the virtual device's VDI 
handle. 

See Also 

TOS, VDI, vap_error, vap_films, vap_state, vsp_message, ysp_state 

Notes 

‘This routine uses the VDI's GDOS in its operation. It should not be used if the 
GDOS is not present in your edition of VDI. 


‘ysp_state—VDI function (libydi.a/vsp_state) 
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Set the Polaroid Palette driver 

include <aesbind.h> 

include <ydibind,h> 

void vsp_state(handle, port, film. lighmess, interlace. planes, indices} 
int handle, port, film, lightness, interlace. lanes, indices|8 2k; 


‘The VDI contains a driver for the Polaroid Palette, a camera that can be used to 
shoot slides directly from the Atari ST, ysp_state changes the settings for this 
driver. 


handle is the virtual device's VDI handle. port is the port to which the camera 
is connected; zero indicates the first communications port. film is the number 
of the film for which the driver is currently set. 


lightness is the intensity to which the driver is set, from -3 through three. Each 
number in this range is equivalent to one third of an f-stop, counting from 
zero. Therefore, -3 has half the intensity of zero, and three is twice as intense 
as zero. 


interlace indicates whether the image is interlaced or not; zero indicates not in— 
erlaced, and one indicates interlaced. Note that an interlaced image requires 
approximately twice the memory of one that is not interlaced, 


planes indicates the number of colors supported. It is set to a code, from one 
through four; one indicates two colors, two, four colors; three, eight colors; and 
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four, 16 colors. 


Finally, indices holds two-character codes for the eight color indices stored in 
ADE format. 


See Also 
TOS, VDI, vqp_error, yap_films, vap_state, vsp_message, ysp_save 


Notes 
This routine uses the VDI's GDOS in its operation. It should not be used if the 
GDOS is not present in your edition of VDI. 


¥st_allgoment—VDI function (libydi.a/rst_allgnment) 
Realign graphics text 
include <aesbind.t> 
#include <vdibind. b> 
void vst_allgament(handfe, horiz, vertical, sethoriz. setvert) 
Int handle, horiz, vertical, *sethoriz, *setvert; 


yst_allgnment is a VDI routine that realigns graphics text. 


Graphics text is aligned both horizontally and vertically, Horizontal alignment 
can be to the left (left justified), to the right (right justified), or centered, Ver- 
tical alignment can be one of the following: baseline, that is, aligned along the 
bottoms of the characters, excluding descenders (the “tails” on letters like ‘jor 

half line, or aligned along the tops of the lower-case letters; ascent line, ot 
along the tops of the upper-case letters; Bottom line, or along the bottom of the 
character cell (i.¢., the bottom of the white space found below the descenders), 
descent line, or along the bottom of the descenders, excluding the white space 
found below them; and top line, or along the top of the character cell (e.g., the 
top of the white space Found shove the capital letters). By default, characters 
are aligned to the left horizontally, and slong the baseline vertically. 


‘The following describes the arguments to yst_allgnment: Aandle is the virtual 
device's VDI handle. horiz is the horizontal alignment you want, as follows: 


0 left 
1 centered 
2 right 
vertical is the vertical alignment you want, as follows: 
0 baseline 
1 half line 
2 ascent line 
3 bottom fine 
4 descent line 
S topline 
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sethoriz and setvert point, respectively, to the horizontal and vertical alignments 
that were actually set. You may wish'to check these values, because not every. 
alignment is available with every type face on every virtual device. 

Example 

For an example of this routine, see the entry for v_gtext. 

See Also 

TOS, y_gtext, VDI 


yst_color—VDI function (Iibydi.a/yst_color) 


Set color for graphics text 

#inelude <aesbind.h> 

#include <rdibind.h> 

int yst_color(handle, color) int handle, color; 

vst_color is a VDI routine that that sets the color for graphics text. handle is 
the virtual device's VDI handle. color is the color being set. See the entry for 
¥_opnwk for a table of legal color settings. 

If the color requested is not available on this virtual device, yst_color sets the 
color to a default of one (black), It returns the color that was actually set. 


See Also 
‘TOS, ¥_gtext, y_opowk, VDI, 


vst_effeets—VDI function (libydi.a/vst_effects) 
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Set special effects for graphics text 

‘dinclude <aesbind.h> 

‘include <ydibind.h> 

Int vst_effects(handle. effects) Int handle, ef fect; 


vst_effects is a VDI routine that sets special effects for graphics text. handle is 
the virtual device's VDI handle. effect is the set of effects that you wish to use, 
as follows: 

0x01 thickened letters 

0x02 lowered intensity 

0x04 slanted letters 

0x08 underlining 

0x10 outlined letters 

0x20 shadowed letters 


For example, if you want letters that are underlined and shadowed, set e/fects 
to 0x28 }x08 plus 0x20). Not every effect will be available on every vit- 
tual device. vst_effects returns the settings for the effects that were actually 
set. 
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Example oe 
For an example of this routine, see the entry for y_gtext. 


See Also 
TOS, v_gtext, VDI 


yst_font—VDI function (libydi.a/vst_font) 
Select a new font 
#include <aesbind.h> 
Winclude <vdibind.b> 
int vst_font(handle, font) int handle, font; 


yst_font is a VDI routine that selects a new font for graphics type. handle is 
the virtual device's VDI handle. font is the code number of the new font avail~ 
able. The number of fonts available on a virtual device can be determined 
either by examined the value returned by the font-loading routine 
vst_load_fonts, or by interrogating the wark_out array returned by y_opnwk 
and ¥_opnywk: work_out/10) contains this information, Use the ro! 
yqt_name to obtain the index number and a description of each available font, 


If you select a font that is not available on the virtual device you are working, 
with, the font will be set to a default; on the screen, the default is the system 
font, yst_font returns the code of the font actually selected, 

See Also 

TOS, ¥_gtext, VDI, vat_name, yst_load_fonts, yst_uatoad_fonts 

Notes 

‘This routine uses the VDI's GDOS in its operation, It should not be used if the 
GDOS is not present in your edition of VDI 

‘This function is not available with every device. To see if it is available on a 


given virtual device, interrogate work_out/10] of the array returned by 
\_opnwk or y_opnywik. 


vst_height—VDI function (Ilbydl.a/vst_helght) 
Reset graphics text height, in absolute values 
#include <aesbind.h> 
#include <ydibind.b> 
yold vst_height(handle. newheight, charwidth, charheight, cellwidth, cellheight) 
int handle, newheight, *charwidth, *charkeight, *cellwidth, *cellheight 


yst_height is @ VDI routine that sets a new height for graphics text. Note that 
graphics text can be resized up to twice its original height; this limit is set to 
reduce the amount of jaggedness, or “aliasing”, present in the characters. 
tst_height resets the characters into absolute values; these values can be either 
in formalized device coordinates (NDC) or raster edordinates (RC), depending 
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‘on which the virtual device uses. On the high-resolution screen, the normal 
character height is 13 rasters, which can be increased up to 26 rasters. 


‘The related function yst_point resets character height, but uses points rather 
than absolute values. Note that the current sizes of a character and a character 
cell can be obtained with the AES routine graf_handle. The number of text 
sizes supported by the virtual device is found in the variable work_oul[5], 
which is part of the array returned by the routines v_opnwk and v_opnvwk, 


handle is the virtual device's VDI handle. height is the new height to which the 
characters are set. Note that not every height is available; if tho height. 
requested is not available, the characters will be set to the next smaller size. 
charheight and charwidth are, respectively, height and width to which the 
characters were set; cel/height and cellwidth are, respectively, the height and 
width to which the character cell is set. Note that the difference in sizes be- 
tween a character and its cell controls how much “white space” appears around 
each character. 


Example 
For an example of this routine, see the entry for ¥_gtext. 
See Also 

TOS, graf_handle, ¥_gtext, VDI, vst_point 


yst_lond_fonts—VDI function (Iibvdi.a/vst_load_fonts) 
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Load fonts other than the standard font 

winclude <aesbind.b> 

include <vdlbind.h> 

int vst_load_fonts(handle, reserved) int handle, font; 


yst_lond_fontsis » VDI routine that loads a virtual device's non-standard fonts 
into memory. The new fonts must be specifically loaded for them to be used; 
this is done in order to save system memory that would otherwise be taken up 
by unused fonts, handle is the virtual device's VDI handle. reserved is reserved 
by GEM-DOS for future use; at present, it should be set to zero. 
yst_load_fonts returns the number of additional fonts loaded. The routine 
yst_unload_fonts should be used to free the memory given over the extra fonts. 
onée they are no longer needed. 


See Also 
TOS, y_gtext, VDI, yst_unload_fonts 


Notes 
‘This routine uses the VDI's GDOS in its operation. It should not be used if the 
GDOS is not present in your edition of VDI. 
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‘yst_point—VDI function (Iibydi.a/vst_point) 
‘Reset graphics text height, in printer's points 
#include <aesbind.h> 
include <ydibind.h> 
void vst_point(handle, newheight. charwidth, charheight, cellwidth, celtheight) 
int handle, newheight, *charwidth, *ckarheight, *cellwidth. *cellheight; 


yst_point is a VDI routine that sets a new height for graphics text. Note that 
graphics text can be resized up to twice its original height; this limit is set to 
reduce the amount of jaggedness, or “aliasing”, present’ in the characters 

{_polnt resets the characters into printer's points; one peints equals 1/72 of an 
inch. The related function yst_height resets character height, but uses absolute 
values rather than points, Note that the current sizes of a character and a 
character cell can be obtained with the AES routine graf_handle, The number 
of text sizes supported by the virtual device is found in the variable 
work_out/5], which is part of the array returned by the routines y_opnwk and 
y_opnywk. 


handle is the virtual device's VDI handle. height is the new height to which the 
characters are being set, Note that not every height is available, if the height 
requested is not available, the characters will be set to the next smaller size, 
charheight and charwidih are, respectively, height and width to which the 
characters were set; cellheight and cellwidth are, respectively, the height and 
width to which the character cell is set. Note that the difference in sizes be- 
tween a character and its cell controls how much “white space” appears around 
each character. 


See Also 
‘TOS, graf_handle, y_gtext, VDI, yst_height 


yst_rotation—VDI function (libvdi.a/yst_rotation) 
Set angle at which graphic text is drawn 
‘include <aesbind.h> 
include <vdibind.b> 
Int yst_rotation(handle, angle) int handle, angle; 


yst_rotation is. VDI routine that sets the angle at which graphics text is drawn, 
handle ig the virtual device's VDI handle, angle is the angle at which the text is 
drawn, in tenths of a degree, On an imaginary clock, zero degrees is set at 
three o'clock, 90 degrees at noon, 180 degrees at nine o'clock, and 270 degrees 
at six o'clock. Not every angle is available on every device; therefore, yst_rota~ 
tion returns the angle at which the text is actually drawn, 


Example 
For an example of this function, see the entry for y_gtext. 
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See Also 
TOS, y_gtext, VDI 


Notes 
‘This function is not available on every virtual device. To see if it is or not, in- 
terrogate work _out/36] of the array returned by y_opnwk or v_opnvwk. 


As of this writing, the Atari ST can rotate text only in 90-degree increments. 


yst_unload_fonts—VDI function (libvdi.a/yst_unload_fonts) 
Unload fonts 
#include <aesbind.h> 
Hinclude <vdibind,h> 
yoid yst_unload_fonts(handfe, reserved) int handle, reserved; 


vst_unload_fonts is a VDI routine that unloads extra fonts used in a VDI 
program. This routine should be used once there is no more need for the extra 
fonts, to free up memory given over to the extra fonts. handle is the virtual 
device's VDI handle. reserved is reserved for a future application, and should 
be set to zero. 


See Also 

TOS, y_utext, VDI, vst_load_fonts 

Notes 

‘This routine uses the VDI's GDOS in its operat 
GDOS is not present in your edition of VDI. 


yn, It should not be used if the 


vswr_mode—VDI function (libydl.a/vswr_mode) 
Set the writing mode 
include <aesbind. b> 
#include <vdibind.b> 
Int yswr_mode(handle, mode) int handle, mode; 


yewe_mode is @ VDI routine that sets the writing mode. handle is the device's 
VDIhandle. mode indicates the writing mode of the device, as follows: one, 
replace; two, transparent; three, XOR (exclusive or); and four, reverse 
transparent, Replace mode simply replaces whatever is on the virtual device 
with the image being drawn. Transparent mode replaces all the zero (white) 
pixels on the device it is overlaying with ones (black), but does not affect black 
pixels that already exist on the screen, The effect is as if the image were drawn 
on a sheet of plastic that was then overlaid on the physical device. Reverse 
transparent mode is the same as transparent mode, except that it affects black 
pixels and ignores white ones. Finally, YOR mode draws an image that later 
can be cancelled out by reversing (or exclusive ORing it), moved elzewhere, and 
redrawn, 
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vswr_mode returns the mode set. 
Example 
For examples of this routine, see the entries for y_circle and y_ellipse. 


See Also 
TOS, VDI 


‘Vsyne—xbios function 37 (osbind.h) 
Synchronize with the screen 
¥include <osbind.h> 
include <xbios.h> 
void Vsyne() 


Vsyne waits for the next picture return from the screen. It is used to synchron- 
ize the system's operation with that of the screen, for specialized effects, 
Example 

For an example of this function, see the entry for VDT. 


See Also 
TOS, xbios 
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we-Command 


Count words, lines, and characters in files 
we [-elw] [file 


we counts words, lines, and characters in each file named. If no file is given, 
we uses the standard input. If more than one file is given, we also prints a total 
for all of the files. 


A word is a string of characters surrounded by white space (blanks, tabs, or 
newlines). 


Options control the printing of various counts: 
-¢ Print acount of character. 

1 Print acount of 
=w Print acount of words. 

‘The default action is to print all counts, 


See Also 
commands 


es. 


wildcards—Definition 


Wildcards are characters that, under special circumst 
range of ASCH characters. Another name for them is 
following is a table of wildcards, and their meanings: 


2 Match any one character, 
* Match any number of characters, including NULL. 


I 1 A set of characters enclosed between ‘[' and ‘]) will match any one 
character of the set, Sets of characters may include ranges, such as [a-z] 
for lower-case letters or [0-9] for numerals, 

J Remove the special meaning of a wildcard. 

See Also 

patterns, 


nces, can represent a 
‘metacharacters”. The 


wind_cale—AES function (libaes.s/wind_cale) 
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Calculate a window's borders or area 

#inelude <aesbind. b> 

int wind_eale(éype, kind, input, output) 

int type; unsigned int kind; Rect input; Prect output; 
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wind_eale is an AES routine that calculates the borders of a window or its total 
area: IF given the work area coordinates, it calculates the borders; if given the 
borders, it returns the total area of the window. type is the type of calculation 
you want performed: zero indicates calculating the borders, and one indicates 
calculating the area. kind indicates the elements contained within the window. 


as follows: 
oxoo1 = NAME title name 
0x02 © CLOSE lose” bar 
oxood = FULL “full” box 
0x008 = MOVE “move” bar 
0x010. INFO information line 
0x020 SIZE size" box 
0x040 = UPARROW —up arrow 
0x080 = DNARROW — down arrow 
Ox100 © VSLIDE vertical “slider 
0x200 «= LFARROW left arrow 
0x400 = RTARROW right arrow 
0x800 = HSLIDE, horizontal “slider” 


All elements used in the window must be mentioned for wind_cale to return a 
correct value. 


input contains the coordinates that are given to wind_cale, It is of the type 
Rect, which is defined in the header file aesbind.h. Rect consists of four 
elements: 

xX coordinate of rectangle 

y  Y coordinate of rectangle 

w width of rectangle 

hh height of rectangle 
output points to the new coordinates as calculated by wind_cale, It is of type 
Prect, which is declared in aesbind.h, as follows: 

tx pointer to X coordinate 

*y pointer to Y coordinate 

sw pointer to rectangle’s width 

*h — pointer to rectangles height 
wind_eale returns zero if an error occurred, and 2 number greater than zero if 
one did not. 
Example 
For an example of this routine, see the entry for window. 
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See Also 
AES, TOS, window 


wind_close—AES function (libaes.a/wind_close) 


“Close a window and preserve its handle 
‘#include <aesbind-b> 
int wind_close(handle) int handle: 


wind_close is an AES routine that closes a window. It preserves the window's 
handié, which was set by the routine wind create, and all of its allocated 
resources, so that it can be reopened, handle is the handle of the window to be 
opened. wind close returns zero if an error occurred, and a number greater 
than zero if one did not. 


Example 

For examples of how to use this routine, see the entries evmt_multi and window, 
See Also 

‘AES, TOS, wind_open, window 


wind _create—AES function (libaes.a/wind_create) 
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Create a window. 
‘include <aesbind.h> 
int wind_create(kind, area) unsigned int kind; Rect area; 


wind_create is an AES routine that creates a new window. kind indicates the 
elements of the window you wish to create, as follows: 
oxo01 = NAME title name 
@x002 © CLOSE “close” bar 
oxood = FULL “full” box 
ox008 = MOVE “move" bar 
0x010 = INFO. information line 
ox0200 SIZE 
Ox040 UPARROW 
0x080 = DNARROW 
0x100 © YSLIDE 
0x200 = LFARROW 
0x400 = RTARROW right arrow 
0x800 = HSLIDE horizontal “slider” 


For example, if you wanted to create a window that had only a title bar and an 
information bar, you would set kind to Ox11 (ie., NAMEUNFO). 


area gives the dimensions of the window. It is of type Reet, which is defined 
in the header file aesbind.h, as follows: 
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X coordinate of rectangle 
Y coordinate of rectangle 
width of rectangle 
height of rectangle 


saun 


wind_create returns either the handle of the window it 
number if it cannot create a window. 


creates, or a negative 


Example 

For examples of how to use this routine, see the entries evnt_multi and window. 
See Also 

AES, TOS, window 

Notes 


As of this wi 
time. 


ing, nO more than six windows can be displayed at any given 


wind_delete—AES function (libaes.2/wind_delete) 
“Delete a window and free its resources 
#include <aesbind.h> 
int wind_delete(handie) Int handles 


wind_delete is an AES routine that deletes a window and frees the resources 
allocated to it, handle is the handle of the window being deleted; this is 
returned by the routine wind_create. wind_delete returns zero if an error ac~ 
curred, and a number greater than zero if one did not. 


Example 

For an example of this routine, see the entry for window. 
See Also 

AES, TOS, window 


wind_find—AES function (Iibaes.a/wind_find) 
“Determine if the mouse pointer is ina window 
Winclade <aesbind.h> 
int wind_find(x, y) Int x, 93 


wind_find is an AES routine that determines if the mouse pointer is positioned 
over @ window. x and y are the mouse pointer’s X and Y coordinates; they can 
be obtained from the AES routine eynt_mouse. wind_find returns the handle of 
the window that the mouse pointer is within, or zero if the pointer is not within 
any window. 
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See Also 


‘AES, TOS, window 


‘wind _get—AES function (libaes.a/wind_get) 


Get information about a window 

clude <aesbind.h> 

wind_get(handle, flag. output! output2, output3, output4) 
*output2. *output3. *out puts 


int handle, flag. “output. 


wind_get is an AES routine that gets information about a window. handle is 
the Randle of the window in question; the handle is set by the routine 
wind_create. flag tells wind_get just what information you want. Unless 
noted, wind_get will set the values for the X coordinate, Y coordinate, width, 


and 


7 


ht, a8 follows: 


WF_WORKXYWH 
WF_CURRXYWH 
WF_PREVXYWH 
WF_FULLXYWH 


WF_HSLIDE 
WF_YSLIDE 
WF_TOP 
WF_FIRSTXYWH 
WF_NEXTXYWH 


Reserved 
WF_HSLSIZE 


WF_VSLSIZE 


WE_SCREEN 


window's working area 
window's total area 

previous window's total area 
window's greatest possible size 
(set wind_create) 
‘outputl set to relative position 

of horizontal slider (11,000; 1=leftmost) 
‘output? set to relative position 

of vertical slider (1-1,000; 1=top) 
‘output! set to handle of topmost window 
First rectangle in rectangle list 

Next rectangle in rectangle list 


output] set to size of horizontal 

slider relative to scroit bar, -1 is minimal 
(small box), 1-1,000 is relative size 
‘output! set to size of vertical 

slider relative to scroll bar; -1 is minimal 
(small box), 1-1,000 is relative size 
Address/length of internal menu/alert buffers: 
output! =low word of address 
outpui2=high word of address 
output3=low word of length 

outputd=high word of length 


wind_get returns zero if an error occurred, and a number greater than zero if 
one did not. 
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Example 
For an example of this routine, see the entry for window. 


See Also 
AES, TOS, window 


wind_open—AES function (Iibaes.. 
‘Open or reopen a window 
include <aesbind.b> 
int wind_open(andie, location) int handle; Rect location 


‘wind_open) 


wind_open is an AES routine that opens or reopens a window. handle is the 
\dow's handle, as set by wind_create. location gives the dimensions of the 
‘window to be opened. It is declared to be of type Rect, which is defined in the 
header file aesbind.h; Rect consists of four elements, as follows 

x X coordinate of rectangle 

y _ Y coordinate of rectangle 

w width of rectangle 

hh height of rectangle 


wind_open returns zero if an error ocsurred, and a number greater than zero if 
one did not. 


Example 
For examples of how to use this routine, see the entries evnt_multi and window. 


See Also 
‘AES, TOS, window 


wind_set—AES function (Iibaes.a/wind_set) 
“Set specified fields within the window 
¥include <aesbind.h> 
Int wind_set(handle, flag. input], input2, input3, inputd) 
Int handle, flag, input, input2, input3, inpurdy 


wind_set is an AES routine that sets specific portions of « window, handle is 
the Kandle of the window to be altered; the handle is set by wind_create. The 
arguments inpu(] through inpul contsin information you wish to insert into the 
window's definition, Note that not all four of these arguments are used with 
every task; those that are not used should be set to zero. flag indicates what 
aspect of the window you want to change, as follow: 


2 WE_NAME Point to new name for window: 
input l=low word of address 
input2=high word of address 

3. WF_INFO. Point to new information line for window: 
input !=low word of address 
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input2=high word of address 
5 WF_CURRXYWH Window's total area: 
coordinate 
inpu2=Y coordinate 
inpajawidth 
inputt=height 
8 WF_HSLIDE input! set to relative position 
of horizontal slider (11,000; 
9 WF_VSLIDE Input! set to relative position 
of vertical slider (1-1,000; 1=top) 
10 WF_TOP input] set to handle of topmost window 
14. WF_NEWDESK ‘Address of new default GEM desktop: 
input I=low word of address 
inpul2shigh word of address 
input3estarting object in tree 


wind_set returns zero if an error occurred, and a number greater than zero if 
‘one did not. 

Example 

For examples of how to use this routine, see the entries evnt_multi and window. 


See Also 
AES, TOS, window 


Jeftmost) 


wind_update—AES function (Iibaes.a/wind_update) 


586 


“Lock or untock a window 
include <aesbind.h> 
int wind_update(/lag) int flag; 
wind_update is an AES routine that locks or unlocks a window. ‘This 
mechanism is provided to prevent a window's information from being updated 
while the screen is being redrawn, to keep information from being “dropped on 
the floor” by GEM. flag indicates what you want done, as follows; 
0 END_UPDATE The update is finished: unlock the window 
1 BEG UPDATE Beginning an update: lock the window 
2 END MCNTRL — End mouse control through user: lock window 
3. BEG_MCNTRL _ Begin mouse control through user: unlock 


wind_update returns zero if an error occurred, and a number greater than zero 
if one did not. 


Example 
For an example of this routine, see the entry for window. 
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See Also 
AES, TOS, window 


window—Definition 
A window is an AES entity that is used to display information. It consists of a 
number of elements, as follows: 


0x00 = NAME Title bar (across top of window) 
0x002 CLOSE Close box (upper left corner) 

oxo = FULL Full box (upper right corner) 

0x008 = MOVE Move bar (across top of window) 
0x010 INFO Information bar (just below move bar) 
0x020 SIZE Size box (lower right corner) 

0x040. “UPARROW —Up arrow 

0x080 = DNARROW —Down arrow 

0x100 —- VSLIDE Vertical slider (right side) 

0x200 = LFARROW —Left arrow 

0x40 RTARROW Right arrow 

0x800 = HSLIDE, Horizontal slider (bottom of window) 


‘The mnemonics used above are defined in the header file gemdefs.h, A window 
can be built with all of these elements, none of them, or any combination of 
them, 


To create a window, use the function wind_create. You must tell this function 
what kind of window is being created (i.e., which elements compose the win- 
dow), and the maximum size that the window can assume. It returns a integer 
handle for the window, which can be used to identify it to all other functions, 
Note that the GEM desktop is always defined as window zero; the desktop is 
defined as being the entire screen minus the menu bar, and this definition is 
handy when you wish to expand a window to fill the entire screen. 


Once a window is created, its attributes must set with the function wind_set, 
For example, if the window being created has a title bar, the text to be written 
there must be set before the window is displayed. 

Once the attributes have been set, you can open the window with the function 
wind_open. You must pass it the handle of the window being created, and the 
dimensions to which you want it opened. 

When a user clicks one of the elements of the window, such as the full box or 
the close box, the AES generates a message which can be picked up with the 
routines evnt__mesag or evnt_multl. Each message is eight ints (16 bytes) long. 
See the entry for evnt_mesag/for a list of the messages. 

When a message is received, the user is free either to react appropriately, or i 
nore the message. For example, if the message WM_FULLED is received, this 
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indicates that the user has clicked the fulled box. The size of the box can then 
be changed with the wind_set routine, and another routine then invoked to 
redraw the screen and remove any debris left. 


When you are done with a window, it should be closed with the wind_close 
function, and then removed with the function wind_delete. Note that the win- 
dow should be closed before deletion; otherwise, you may not be able to erase: 
the old, left-over window from the screen, 


Redrawing @ window 

‘The interior of each window is broken by the AES into a set of non-overlap- 
ping rectangles, which it records in a list. If only one window appears on the 
screen, then its interior is described as one rectangle; if there are two windows 
on the screen, however, and one overlaps the other, then the interior of the 
lower window is described as a set of rectangles that outline the area being 
encroached, Therefore, redrawing the interior of a window requires that exch 
rectangle be redraw in turn; cycling through the rectangles and redrawing them. 
is called “walking the rectangles". The dimensions of the first rectangle in the 
list can be obtained with the following call: 


wind getchendle, WF_FIRSTIOW, thor.t, Boxy, Ubor.w,, Bkox.h)s 
and the dimensions of the next rectangle with this call: 
Wind getthandie, MF_NEXTCHUN, BboK.R, boty, BboK. My, Rbox.bD; 


AES returns zero for the width and height when it has reached the end of the 
rectangle list 


Example 

The following example demonstrates a number of window routines. It draws 
two windows, one on top of the other, Each has a title bar, a full box, an exit 
‘box, and boxes for moving and changing the size of the window. Clicking the 
exit box closes the window; when all the windows are closed, the program ends, 
A redrawing function is included; it "walks the rectangles" to fill the interior of 
each window with a gray mask, For more information on the object that it 
draws, see the entry on object. Note that the number of windows generated can 
be increased by redefining the manifest constant LIMIT. 


include <aesbind.h» (f Contains AES bindings */ 
include <gendefe.h> /* Contains manifest constants */ 
include <obdefs.h> [f Containe ebject definitions */ 
‘ictine YES t 
iefine MOO 


‘Bdetine DESKTOP © 
fief ine KINO (NAME | CLOSER | FULLER | INFO | SIZER | MOVER) 
‘éefine LIMIT 2 /* Maximum punber of windows */ 


ms C 


Lexicon 


window 


Misting SPEC Ox1SIEIL 


Tee: (1 ee 16) | 
Geuace << 12) | 
Gace << 8) | 
men | 
wed | 


reer irs) 


auack 
7 

/* Rectangles used throughout progras */ 
Rect tempbox = C250, $0, 150, 300 9; 
Pract tenpptr = ( Btempbox.x, Btempbor.y, 
Rect fullbox = (0, 0,0, 03; 

int nowhere = 0; 

/* Strings used in window: must be global 
char title» * TITLE +; 

char info = "thle Uns window; 


order 1 raster thick! 
TFL color; BLACK = 11 
Mext color} 

Turn on replace Bitz 

IFILL pattern to gray] 
Trogether make one nytbtel > 
Border color} 


1° 0x written by wind get, ete. */ 
[Rtespbor.x, Btempbox.h 
77 To be set to desktop dimensions */ 


” 
or static, oF could atep on memory */ 


7° Window’ eitle string */ 
[0 Window infarmacion tering "7 


(* Unused pointers point herv 


[7 Object used to mask interiors of windows */ 


OBJECT masktd = ¢ 
7% next/nendstelly type / flags / 2% 


Ty ot) 7% §80%, LASTOR, NORMAL, SPEC, 


o% 


imine ¢ 
7" Declarations for windows */ 
Het handle Limt3 
int ne 0; 
Jt Declarations for emit meseat) */ 
nt buffer (8) 
int fulled » Ko; 
int window = 1; 
/* Open application */ 
‘oppl_inits 
af mouse (ARROV, nowhere): 
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Ispecitication x. Ws 17 
1) 1, 639, 359 


(1 Vindow handle */ 
77 number of handle */ 


(* Butter for messages; each Is 8 ints Long */ 
7 Flag: hae window been "ful Led? +7 
7 Flag: sbich window 13 being handled? 


1” open appl feation */ 
(fe Moke pee an crea "/ 


589 


window Lexicon 


/* Get desttap dimensions; create and open windows *"/ 
wind get (DESKTOP, UF_FULLEN, 

Efullbox.t, Sfullbox.y, Bfultboxw, ful tbox.h: 
‘obje_drawinask, R00T, 0, fullbox); [* Coat screen with gray color */ 
for (n= 0; n <UIMiT; nt) € 

gref_growox(], 1, 1, 1, tempton; — /* *star wares */ 

hhandletm = wind create(Kiso, fullbox); /* Get handle */ 

Wind gettrandiethd, 2, title, 0, 0); | /* Set window ¢ 

‘'eetthandietn), 3, info, 0,'0); /* Set info tine */ 
Mindloperthendtetd, tempten); 7 open window #7 


si 


> 


7* Now, walt for something to happen */ 
torcsi? € 
‘evnt_meseg(but fer); 
ssuitencbuttert01) ¢ 
case WH REDRAM: 
Fedrat buffer (319; 
break; 
‘cane WH TOPPED: 
ind setCbutfer (5), WF_TOP, Knowhere, 
Enohere, nowhere, Lnowbere) 


bees 


ense m FULLED: 
Ft (fulled == YES) ¢ 
wind get(buffer(S), WFLPREVKYUM, eepptrd 
graf_sheinkbox(tenpbex, ful (box); 
Mind.sectbuf ter), WF_CURRKWN, compton) 
fulled = M0; 
deter 
wind getitutfer(3), WFCURRKYUN, tesppte); 
if groxbortrempeox, Ful lbox); 
Wind_aet(butfer(S], UF_CUREKTHM, fullbox); 
fulled © YES; 


> 
break: 


case (a 51260: 
case \AAOVED: 
Tenpbox.x = buffer (él: 


Wind set(butfert31, WF coer, 
fulled = so: 
breaker 
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write 


cane W_cloeen: 
departtbuffer 31, 
windows; 
break; 

default: 
breaks 

> 


d 


(1 Wask out interior of window */ 
redrau(windrardle) 
int windhardle; 


« 
graf_nousech OFF, Snouhere); r 
Wind] update CEG UPDATED: ” 
Mind get(windhandle, UF_FIeSTICH, teepota: 7+ 
Mit LeCtonpbor.w bk fexpbor.h) 
ble craugmask, ROOT, 0, terpbexd; —/* 
wind get windhandle, UF'NEXTKYMK, tempptr: 
7 
> 
Wind. updatecEND_UPOATED: rel 
(graf eousech OX, Knownered; ” 
return; 
¥ 


J Exit from the prooras *7 
depart(uirdhandie, (19g) 
Int windhandte, fea; 

¢ 


wind, 
wind-closecwiechandie); 
Mind deletecvinchandle): 


arafahrinkbest, 1, 1, 1, tenpbes); 


44 (flag < LiKET) 


else ¢ 
appl_exit()s 
exit); 
> 
y 
‘See Also 


AES, gem, gemdefs.h, object, TOS 
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Cwlnhandle, UF_CURRKYW, tempter): 


Leek wineow #7 


Get Ist rectangle */ 


Draw rectengts 


” 


Get next rectangl: 


Unlock window #/ 
Show mouse */ 
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Write to a file 
write(fp, buffer, re) 
int /p; char *buffer; int n; 


write writes bytes of data, beginning at address buffer, into the file fp. 
Writing begins at the current write position, as set by the last call to either write 
or Iseek. write advances the position of the file pointer by the number of 
characters written. 


Example 
For an example of how to use this function, see the entry for open. 


See Also 
STDIO, UNIX routines 


Diagnostics 

write returns a value of -1 if an error occurred before the write operation com- 
menced, such as a bad file descriptor /p or invalid bu/fer pointer. Otherwise, it 
returns the number of bytes actually written. It should be considered an error 
if this number is not the Same as 1. 


Notes 


write is a low-level call that passes data directly to TOS. It should not be inter 
mixed with high-level calls, such as fread, fwrite, or fopen without care. 
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xbios—TOS function (libe.a/xbios) 
Call a routine from the extended TOS BIOS 


#include <osbind.h> 
extern long xbios(7. /1, /2 


Ix} 


xbios allows you to call a routine directly in the Atari extended ROM BIOS, by 
triggering trap 14. n is the number of the routine, and // through fx are the 
parameter numbers to be used with xbios, In most circumstances, it is unneces- 
sary to call xblos, for the header file osbind.h defines a number of Functions 
that use it directly. The constants and structures used by these functions are 
contained in the header file xbios.h. 


‘The following are the xbios functions: 


Bloskeys 
Cursconf 
Dosound 
Flopfmt 
Floprd 
Flopyer 
Flopwr 
Getrez 
Gettime 
Giaccess 
Ikbdws 
Initmous 
lorec 
Sdisint 
Jenabint 
Keytbl 
Kbdvbase 
Kbrate 
Logbase 
Mfpint 
Midiws 
Offgibit 
Ongibit 
Physbase 
Protobt 
Prtbike 
Puntaes 
Random 
Rsconf 
Serdmp 
Setcolor 
Setscreen 
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restore the default keyboard table 
set the cursor’s configuration 
pass data to the sound daemon 
format a floppy disk 
read a floppy disk 
verify a floppy disk 
write to a floppy disk 
read the current screen resolution 
read the current system time 
write to the GI sound chip registers 
send commands to the intelligent keyboard 
initialize the mouse 
Ret a pointer to the serial device input record 
disable an interrupt 
enable an interrupt 
create a new keyboard table 
get-a pointer to a set of keyboard routines 
set the keyboard's repeat rate 

et the screen’s logical base 
initialize interrupt routine in multi 
send string to musical instrument digital 
the sound chip's A port 
the sound chip's A port 
et the physical base of the screen 
create a prototype boot routine 
print a dump of the screen 
make AES go away 
generate a pseudo-random number 
configure the RS-232 (serial) port 
print a dump of the screen 
set a color 
set the screen parameters 
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Setpallete set the color pallette 
‘Setpre configure the printer port 
Settime set the system time 
Supexee run a function under supervisor mode 
‘Ysyne synchronize with the screen refresh 
Xbtimer initialize a timer on the multi-function port 
See Also 
osbind.h, TOS 
Notes 


Note that no xbios function checks for bogus device numbers. Passing a bogus 
device number to one will crash the system. 


Note that all xbios 1/O routines, including file 1/0, are unbuffered. Combining 
them with buffered 1/0 routines, such as those in the STDIO library, will lead 
‘at best to unpredictable results. 


h—Header file 
#include <xbios.h> 


xbios.h is a header file that includes all constants and structures used by the 
GEM-DOS xbios functions, For a list of these functions, see the entry for 
xbios. 


See Also 
bios.h, header file, TOS, xbios 


Xbtimer—xbios function 31 (osbind.h) 


Initialize the MFP timer 

include <osbind.h> 

‘sinclude <xbios.h> 

void Xbtimer(simer, control, data, buffer) int timer. control.data; char *buf fer; 


Xbtimer permits you to initialize one of the 68901 chip's timers, timer is a 
value from zero through three, which corresponds to timers A through D, 
respectively, Timer A handles’ user applications; timer & handles graphi 
timer C is the system timer; and timer D sets the baud rate for the RS-232 port. 
control sets the timer's control register, and data is a byte of data to be written 
into the timer's data register. bu/fer points to an interrupt handler. 


See Also 
‘TOS, xbios 


XOFE_Definition 


394 


XOFF is a flow-control signal used with asynchronous communications. Usu- 
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ally, it consists of a <ctrl-S> character, and is sent by the receiving device when 
its asynchronous buffer is nearly full, or has reached the “high-water mark". 
Note that when XOFF is used to help control data transmission, binary files 
cannot be transmitted. 


See Also 
XON 

XON—Definition 
XON is a flow-control signal used with asynchronous communications, Usu- 
ally, it consists of a <etrl-Q> character, and is sent by the receiving device 
when its asynchronous buffer is nearly empty, or has reached the “low-water 
mark”. Note that when XON is used to help control data transmission, binary 
files cannot be transmitted, 
See Also 
XOFF 
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:337 


assert: 39 
define: 162 
include: 265 


& 4,337 

Ye: 26, 378, 404 
&&; 338 
“12,337 

2 126 

A337 


+338 


212,337 


(337 
ia 


4337 


_stksize: 27, 432 
“tolower: 462 
~toupper: 466 


abort: 52 
abs: 52 
cos: 53 
address: $4 
AES: 54 
‘compiling with AES library: 54 
description: 29 
object: 351 
window: $87 
acsbind.h: 58 
aliosing: 340 
alignment: 58 
altering stack size: 21 
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appl_exit: 59, 260, 584 
appl_find: 59 
appl_init $9 
appl_read: 60 
appl_tplay: 60 
appl_trecord: 60 
appl_write: 61 

ar. 6: 

arena: 63 

arec: 64 

argy: 64 

array: 66 

as 21, 67 

as6Btoas: 83 

ASCTL: 83, 

asctime: 87 

asin: 88 

assembler: 67 

assembly language output: 21 
assembly language programs: 21 
assert: 88 


‘automatic mode: 18 
aux 11 


backspace: 96 
96 


Beonout: 98 
Beonstat: 98 
Beostat: 99 
binary files: 212 
BIOS: 101 

bios: 29, 100 
bios.h: 89 
Bioskeys: 101 
bi 101 
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Index 


bit map: 101 
block 1/0: 25 

bombs: 102 

boot; 102 

buffer: 103 

byte: 103 

byte ordering: 103, 
byte-by-byte 1/0: 23 


C language: 105 

€ preprocessor: 17 

cabs: 108 

calling conventions: 108 

alloc: 27, 113 

canon.h; 113 

carriage return: 24, 113 

case sensitivity: 16 

cat: 12, 114 

Cauxin 114 

Cauxis; 115 

Cauxos 116 

Cauxout: 116 

ec: 15, 116 
MicroEMACS mode: 18 
-VGEM; 464 
-VGEMACC: 465 

ec: 17, 121 

eck: 17, 122 

ee2: 17, 12 

ee3: 17, 122 

Ceonim: 122 

Ceonts; 123 

Ceonos, 124 

Ceonout: 124 

Coonrs; 125 

Ceonws: 125 


character constant: 127 
character quotations: 337 
character string 
definition: 22 
clearerr: 128 
CLK_TCK: 128 
clock: 129 
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close: 129 
slosing a FILE: 23, 


cp: 9, 135 
cpp: 135 
curscon 
date: 148 
aby: 149 
af: 166 
diff: 169 
make: 303 


145 


mtol: 341 

my: 8, 342 

nm: 32, 343 

od: 31, 362 

pr 376 

pwd: 387 

rm: 9, 397 

rmdir. 8, 397 
397 


setpal: 413 
setphys: 413 
setprt: 414 
setrez: 415 
show: 421 
showmouse: 421 
size: 422 
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sleep: 423 
smap: 423 

sort: 423 

unset:6 

we: 580 

command files: 340 
command processor: 4 
command separators; 338 


compiling from the GEM desktop: 15 
compiling with Mark Williams C: 15 
compiling without linking: 20 
compound number: 133 

con: 11 

cox: 134 

cosh: 134 

cp: 9, 135 

cpp: 17, 135 

Cprnos: 137 

Cproout: 137 

Crawein: 138 

Crawior (38 

erent: 139 

erte().0: 139 

ertsd.o: 140, 465 

ertsg.o: 140, 464 

esheony: 141 

time: 142 

etype: 143 

etypesh: 144 

Cursconf: 145 

cursconf: 145 


daemon: 147 

data formats; 147 

data types: 147 

date: 148 
dayspermonth: 149 

ab: 149 

setting registers: 151 
the debugger: 31 
Dereate: 159 

Dielete: 160 


debugging programs: 31 

declarations: 161 

desk accessory: 162 
1: 166 

Dfree: 167 

Dgetdry: 168, 

Dgetpath: 168 

diff: 169 

iftime: 170 

directories: 8 

directory: 170 

disassembler: 17 

Dosound: 170 

double: 173 

drtomw: 173 


Dsetpath: 175 
dap: 177 
dap: 178 
dynamic memory allocation: 27 


echo: 11-12, 179 

ecyt: 179 

edata: 179 

egrep: 180 

end: 181 

enum: 182 

eaviron: 183 

environment: 339 

eavironmental variable: 
HOME: 7, 263 


LIBPATH: 290 
PATH: 368 


environmental variables: 6 
enyp: 183, 

EOF: 24, 183 

errno: 184 

errno-b: 184 

error codes: 184 

error messages: 35 


etext: 185 
evat_button; 136 
evnt_delick: 187 
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example: 51 
executable file: 16, 194 
executable files: 19 
executable program: 17 
cexecve: 194 

exit: 23, 195 

exit button; 222 

195 


fabs: 
factor.c: 19 
Fattrib: 198 
Felose: 200 
felose: 23, 199 
Fereate: 200 
fevt: 203 
Fdatime; 203 
Fdelete: 205 
Fdup: 205 
feof; 24-25, 205 
ferror: 24-25, 206 
flush: 206 
Fforce: 206 
fgete: 207 
208 
5: 25, 209 
fgetw: 210 
fields 211 
FILE: 212 
file: 211 

ASCIL 212 

binary: 212 

mode: 23 

name: 23 
file descriptor: 212 
file name substitutions: 337 
file redicection: 338 
FILE type: 23 
file-name substitutions; 11 
fileno: 212 
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Mexible arrays: 212 
float: 213 
Hoating point output: 20 
floor: 215, 
Flopfmt: 215 
Floprd: 218 
Flopver: 219 
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1, Introduction 


make is a utility that will help you construct complex C programs. It will relieve you 
of much of the drudgery needed to piece together a complex program; when properly 
used, make will save you a great deal of time. 


If you are new to Mark Williams C, you should first examine the Mark Williams C 
compiler manual, which will give you the background information you need in order 
to read this tutorial with understanding. 


What is make? 
make is a program-building discipline that runs under msh. This means that make 
governs the piecing together of a complex C program, 


Unlike programs in BASIC or Pascal, a C program consists of one or more odject 
modules. Each object modute, in turn, is produced by compiling or assembling one or 
more files source module of code written in C or assembly language. 


A simple program can consist of only one source module. For example, the program 
hello is generated by compling only one source module, called hello.c; all that is 
‘needed to generate hello is the command: 


ce hello.e 


If you were to alter hello.c, regenerating hello would be easy. 


In contrast, generating a complex program can be difficult. C source modules may 
refer 10 header files that may be changed independently of the source module itsell. 
‘A compilation may require that certain macros be defined on the command line, and 
linking may use special libraries, For example, the source code for the sereen editor 
MicroEMACS, which is included with the Mark Williams C distribution, consists of 
numerous source modules and one header file. Generating MicroEMACS requires. 
either that more than one ce command be used, or that all files be placed into a 
special directory for compilation, 


Naturally, a complex program is never compiled only once. A program may nerd to 
be recompiled many times, as it is tested, debugged, and improved. A programmer 
faces two problems in recompiling a complex program. First, a mistake in recompila~ 
tion can geeatly complicate the task of debugging the program: an incorrect compila- 
tion will introduce errors that may take a long time (o isolate and correct, Second, 
recompiting all the source modules in a complex program can take a great deal of 
valuable time, which is largely wasted, 


One strategy for coping with this situation is to write a script that contains all the 
commands needed to generate the program. This solves the problem of errors, by en~ 
suring that all the file names are correct and all the commands are structured cor— 
rectly; however, it does not solve the problem of wasted time because using a script 
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demands that all source modules be recompiled every time the program is regenerated, 


‘The other strategy is to rewrite the compilation commands by hand every time the 
program is regenerated. This solves the second problem, of wasted time, by allowing 
You to recompile just the source modules that you have altered; however, this method 
leaves your program vulnerable to errors, because entering complicated sequences of 
program generation commands is tedious. 


make is a program building discipline. It simplifies the process of building a complex 

program by combining the best of the two strategies For generating programs, Errors 

are eliminated, because you place the names of all source modules and the text of all | 
compilation commands into one makefile, which is reused every time the program is 
regenerated; and time is saved, because make checks all source modules, libraries, and 

header files, and recompiles Only those that have changed since you last generated 

your program. As you can see, make simplifies and speeds the task of generating 

complex programs. 


‘Try make 


‘The following example will show that make is extremely easy to use. Before you 
begin, however, make sure that Mark Williams C is up and running. If this has not 
yet been done, consult chapter | of the Mark Williams C manual, which will tell you 
what you need to do, 


Before you begin to work the example, enter the Mark Williams Company micro-shell 
msh. If you do not know how to use msh, see the section on using msh in chapter II of 
the Mark Williams C user's manual before you continue. 


Also, note that make works by examining the times when your source files and object 
‘modules were created. If you do not reset the time on your Atari ST whenever you 
reboot, every lime, make will not work correctly. | 


‘To test make, create a directory called factor, then move the following files into it: 


atod.e 
factor.c 
nakefile 


‘These files are included with your release of Mark Williams C. 
Now, type make. The following will appear on your screen: 
ee -D -e factorse 


ce -D -e atod.c 
ee -0-f sof 


tor.prg factar.e atod.o -Le 


You may also see some warning and strict messages from the compiler as it processes 
each file, 
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When the msh prompt returns, type 
factor 


‘Then type a number. factor will calculate factorial numbers and return them to the 
sereen, You can leave factor by typing q. 


Now, type make again, Ina moment, make will quietly exit, and you will see the msh 
prompt again, What happened was that make checked the dates and times of the oh- 
hect modules and of the source modules, saw that the object modules were younger 
than the source modules, snd so compiled nothing. 

Now, use the MictoEMACS screen editor to open the file factor.e for editing, Insert 
the following line into the comments at the top: 


* this comment (x for test purposes only. 


Now exit. Type make once again. This time, you will see the following on your 
soreen: 


ee +0 + factor.e 
ce -0-f 0 factor.pre factor.e stod.o 


make recompiled factor.c because you altered it, and relinked the altered object 
module into the finished program. It did not touch atod.c because it had not been 
changed since the last time you compiled factor. 


‘As you can see, make greatly simplifies the construction of a large, complex C 
program, 


‘This tutorial will show you how to use make, Chapter 2 introduces you to the essen~ 
tials of make; chapter 3 presents more detailed information for the sophisticated user. 
Chapter 4 summarizes make and its options, and gives a table of error messages with 
suggestions for how to deal with them. 
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2. Essential make 


Although make is 2 powerful program and has many features, its basic features are. 
easy to master. This chapter will show you how to construct elementary make 
programs. 


‘The makefile 


When you invoke make, it looks in your present directory for a file named makefile, 
makefile is a text file that you create; it holds all of the information that make needs 
to build your program, For this reason, the makefile is called a program specification. 


A makefile has three basic elements. 


First, the makefile begins with a target line that names the program you wish to 

called the target program. The name of the target program is followed by a 
',and then by the names of files out of which the target file is to be generated, 
For example, if you wished to build the program feud.prg out of the files hatfield.c 
and mecoy.c, you would type: 


feud.pra: hatfleld.o mecoy.e 


Note that you must give your source modules the .o suffix, which refers to their com~ 
piled form as object modules, If the files hatfield.o and mecoy.o do not exist, make 
knows to create them from the source modules hatfield.c and mecoy.c. 


‘The second element is one or more command lines, The command line gives the sc~ 
tual command for compiling the program in question. The only difference between a 
makefile command line and an ordinary ce command to the compiler is that the 
makefile command line must begin with a spsce or a tab character. For example, the 
makefile to generate the program feud.pre described above must contain the 
following command line: 


ce +0 fexd.prg hatfield.o necoy.o 


For a detailed description of the ce command line and its options. refer to the entry 
for ee in the Lexicon. 


‘The makefile may also contain additional target and command fines that describe how 
to build other components of the program. These are described in chapter 3 of this 
tutorial. 


The third element is a list of header files that your program uses. These are given $0 
that make can check to see if they have been modified since your program was last 
generated. For example, if the program hatfield.c used the header file shotgun.h and 
mecoy.¢ used the header files rifle.h and plstol.h, the makefile to generate the 
program feud would include the following lines: 
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recoy. 


Fiflesh pistot.h 
‘Thus, the entire makefile to generate the program feud.prg appears as follows: 


fead.pra: hatfietd.o meoy.o 
‘ce 70 feud.prg hatffeld.o mccoy. 


hatfield.o: shotgun.h 
rnecoy.o: riflesh pistol. 


(e, (00, that a makefile may also contain macro definitions and comments. These 
will be described below. 


Building a simple makefile 


‘The program factor.prg is generated out of two source modules, called factor.c and 
atod.c. The mathematics library libm.a is required, but no unique header files are 
used. Asan exercise, write the makefile needed to generate factor.pre. 


(One solution is the following: 


fector.prg: faetor.0 atod, 
ce -0 fector.prg factor. 


‘As you can see, it is not necessary to specify header files if none are used. 


‘Comments and macros 


If you wish, you can embed comments within a makefile. Any line that begins with a 
pound sign'*#" is ignored by make, and so can hold information that describes the 
makefile to other users, For example, you may wish to include the following infor~ 
‘mation in your makefile for factor: 


4 This makefile generates the progran "factor 
# "factor consiste of the source mdules "factor.c™ and 
# vated.c. It uses the Standard mathematics (ibrery 
Hlibm, but it requires no spectal header files. 


factor.pra: factor.0 atod.o 
(ee +0 factor.prg factor.o stod.o -| 


‘You can also define macros within your makefile. A macro is a symbol that stands 
for a string of text. Usually, a macro is defined at the beginning of the makefile, 
using a macro definition statement. This statement uses the following syntax: 


SSIWBOL = string of text 
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Whenever the symbol is used in your makefile thereafter, it must begin with @ dollar 
sign 'S' and be enclosed within parentheses. 


Macros are usually used to eliminate the chore of retyping long strings of file names, 
For example, with the makefile for the program factor, you may Wish to use a macro 
to substitute for the names of the object modules out of which it is built. This is done 
as follows: 


# Thin makefile generstes the progran "factor". 

A "factor consists of the source modules Mactor.c™ and 
f ratod.c". Tt uses the standard nathonatics {ibrary 

A Libmt, but ft requires no special header files. 

082 = factor.0 stod.o 


fnctor.prg: $(081) 
‘ee 0 factor.prg $184) -\m 


Note how the macro OBJ is used in this Makefile. If a macro is used that has not 
been defined, make will substitute a NUL character for it. The use of a macro makes 
sense when generating large files out of a dozen or more source modules. You avoid 
tedious retyping of the source module names, and potential errors are avoided. 


Setting the time 


‘As noted above, make checks to see which source modules have been modified before 
it regenerates your C program. This is done to avoid the time-consuming and useless 
task of recompiling source modules that have not been updated. 


make determines that a source module has been altered by comparing its date against 
that of the target program. For example, if the program factor.pre was generated on. 
March |6, 1985, at 10:52:47 A.M., and the source module atod.c was then modified on 
March 20, 1985, at 11:19:06 A.M., make will know that atod.c needs to be recompiled 
because it is younger than factor.prg. 


For this reason, if you wish to use make, you must reset the date and time every time 
you reboot your system. Some users do not do this routinely; however, unless the time 
is reset every time, make will be useless. 

Use the command date to reset the date. date is described in the Lexicon, chapter IV 
of the Mark Williams C manual, 


make uses two routines to handle time: ftime, which reads the time from TOS, and 
ctlme, which translates what ftime has read into a format useful to make. For details 
‘on how these routines work, see the entries for ftime and ctime in the Lexicon, 
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Building a large program 


As shown earlier, make can ease the task of generating a large program. The 
Following is the makefile used to generate the screen editor MicroEMACS: 


* 
@ Makefile for MicroEHACS on the Atari ST 
* 


CFLAGS = -0 
LFLAGS = Lib\Libtem.2 
Otdeans!.o basie.o buffer.o disptay.o file.o \ 
line.o main.o rardon.o region.¢ search.o \ 
spawn.o teap.o termio.o viS2.0 window.c word. 
wme.ttp: S(08)) 
ce -0 we.ttp $084) 
(084): eh 


‘The first line is commentary that describes the file. 


The next five lines define macros that are used on the target and command fine. The 
First macros will be discussed in the following chapter, on “Advanced make". The 
second macro substitutes for the name of a special library that is needed to create this 
program. The third macro, which is three lines long, is defined as standing for the 
names of the source modules that produce MicroEMACS. Note that a backslash ‘\’ 
must be used to tell make that the definition is carried over onto the next line. 


‘The next line names the target file (me) and the files used to construct it, here 
represented by the macro OBJ. 

Next comes the command line, which dictates the compilation to be performed, Note 
that the macro LFLAG must follow the the names of the files to be compiled. Note 
that this line must be preceded by a space or a tab. 


‘The last line lists the header file ed.h, which is required by all of the files used to 
generate MicroEMACS. 


‘Command fine options 


Although what make does is controlled largely by your makefile, you can also affect 
what make does through the use of command line options. These options allow yau to 
alter make’s activity without having to edit your makefile. 

Options must follow the command name on the command fine and start with a hyphen 
‘1, using the following format (note that the square brackets merely indicate that you 
can select any of these options, and are not used on the make command line): 


make  -dinpgest 1 -¥ filename 
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These options are described below. 


-d (debug) make describes all of its decisions. You can use this to debug your 
makefile. 


=f filename 
(file) option tells make that its commands are ina file other than makefile. For 
example, the command 


rake -f snith 


tells make to execute the file smith rather than makefile. If you do not use this 
option, make will search the directories named in the PATH environmental 
variable for a file entitled makefile to execute, The command line can hold 
more than one -f option. 


<i (ignore errors) make ignores error returns from commands and continue proces 
sing. Normally, make exits if a command returns an error status. 


=n (no execution) make tests dependencies and modification times but does not ex- 
ecute commands. This option is especially helpful when constructing or debug- 
ging a makefile, 

=p (print) make prints all macro definitions and target descriptions. 

=q (question) make checks if the target is up to date and returns an appropriate 
status without executing any commands. “Up to date” means that the target 
program is younger than all of its source modules. make returns 0 if the target 
is current, | if an error occurs, and 2 if the target is outdated. 

<r (rules)_make does not use the default macros and commands from 
LIBPATH\mmacros and LIBPATH\mactions, These files will be described in 
the following chapter. 

-s (silent) make does not print each command line as it is executed, 


= (touch) make changes the modification time of each target to the current time, 
‘This suppresses actual regeneration. Although this option is used typically after 
a purely cosmetic change to a source file or after adding a definition ta a header 
file, it must be used with great caution. 


Other command line features 


In addition to the options listed above, you may include other information on your 
command line. 


First, you can define macros on the command line. A macro definition must follow 
any command line options. Arguments including spaces must be surrounded by 
quotation marks, as spaces are significant to msh. For example, the command line 
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make -n -f smith “0Biea.0 b.o* 


tells make to run in the no execution mode, reading the file smith instead of makefile, 
and defining the macro OBJ to mean a.0 b.o. 


‘The ability to define macros on the command line means that you can create 2 
makefile using macros that are not yet defined; this greatly increases make's 
flexibility and makes it even more helpful in creating and debugging large programs. 
Another feature is the ability to change the name of the target file on the command 
Tine, As will be discussed in full in the next chapter, a makefile can name more than 
one target file. make normally assumes that the target is the first target file named in 
makefile. However, the command line may name one or more target files at the end 
of the line, after any options and any macro definitions. 


To see how this works, recall the program factor described above. factor is generated 
out of the source modules factor.c and atod.c. With this program, the command 


make atod.o 


with the makefile outlined above would result in the following ce command line 
being produced: 


ce -¢ atod.e 


if the object module atod.o does not exist of is outdated, Here, make compiles atod.c 
to create the target specified in the make command line, that is, atod.o, but it does 
not create factor. This feature allows you to apply your makefile to only @ portion of 
your program. 


The use of special, or alternative, target files will be discussed in full in the next 
chapter. 
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3. Advanced make 


‘This chapter describes some of the advanced Features of make. Most programs do not 
require these features; however, users who create extremely complex programs will 
find these features to be most helpful. 


Default rules 


The operation of make is governed by a number of defaul rules. These rules were 
designed to ease the compilation of a typical program; however, unusual tasks may be 
made easier by bypassing altering the default rules, 


To begin, make uses information from the files LIBPATH\mmacros and 
LIBPATH\makeactions to define default macros and regeneration commands. make 
looks for these files in the directories named in the LIBPATH environmental variable, 
make uses the command: in mmacros and mactions whenever the makefile specifies 
‘no explicit regeneration commands, The command line option -r tells make not to 
use the macros and actions defined in mmacros and mactions. 


‘As shown in earlier examples, make knows by default to generate the target atod.o 
from the C source atod,c with the command 


ce 0 +e ated.e 


‘The macro SUFFIXES defines the suffixes make knows about by default. [ts defi 
tion in mmacros includes both the .o and .c suffixes. 


mmacros uses targets such as .c.0 to specify the commands for recreating a .0 object 
file from a .e source file. The entry for this target is as follows: 


we story ve 86 


Macros CC and CFLAGS are defined in mmacros as: 


cece 
CFLAGS = -0 


You can change the name of the default C compiler that make uses by supplying a 
new definition of macro CC or can change the default compilation flags by redefining 
CFLAGS. 


make's files mmacros and mactions use several other pre-defined macros to increase 
their scope and flexibility. These are as follows: 


* s<"", which is used in the above example, stands for the name of the file or 
files causing the action of a default rule. in the above example, S< stands for 
the file name atod.c. 
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* stands for the name of the target of a default rule with its suffix removed, 
If it had been used in the above example, $* would have stood for atod, 


“Ge and 
in a makefile. 


may be used only with default rules; these macros will not work 


“g2" stands for the names of the files that cause the action and that are younger 
than the target file. 


‘The macro “S@" stands for the target name. 


Macros “$?" and “S@" may be used in a makefile. For example, the following 
rule updates the archive libx.a with the objects defined by macro $(OBJ) that 
are out of date: 


ibs, 


(081) 
ar ev Uibe.s $7 


mmacros also contains default commands that describe how ta build additional kinds 
of files: 


* AS and ASFLAGS call the assembler to assemble .0 files out of .s files, 


You can change the default rules of make by changing them in mactions and chan- 
ging the definition of any of the macros as given in mmacros. 


Double colon target lines 


An alternative form of target line simplifies the task of maintaining archives. This 
Form uses the double colon "':" instead of a single colon “ to separate the name of the 
target from those of the files on which it depends. 


A target name can appear on only one single-colon target line, whereas it can appear 
on several double-colon target lines. The advantage of using the double-colon target 
Jines is that make will remake the target by executing the commands (or its default 
commands) for the first such target line for which the target is older than a file on 
which it depends. For example, for the program factor.prg described earlier, assume 
that two versions of the source files factor.c and atod.c exist: factora.c plus atoda.c, 
and factorb.c plus atodb.c The makefile would appear as follows: 


Bt = fectore,o steda.o 
B12 = factorb.o stowb.0 


factor.pea #1 $(0841) 
ce -¢ $(0Bs1) -lm 
fector.pra :: S(OBs2) 


eee $(082) -lm 


This makefile tells make to do the following: (1) check if either factora.o or atoda.o 
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are younger than factor.prg; (2) if either one is, regenerate factor.prg using this ver— 
Sion of these files; (3) if neither factora.o nor aloda.o are younger than factor-prg, 
then check to see if either factarb.o or atodb.o are younger than factor; and (4) if 
pither of them are, then regenerate factor.prg using the youngest version of these 
files. 


This technique allows you to maintain multiple versions of source files in the same 
directory and selectively recompile the most recently updated version without having 
to edit your makefile or otherwise trick the system. 


Note that a file may not be targeted by both single-colon and double-colon target 
lines. 


Alternative uses 


make is almost always used to control the generation of complex C programs. 
However, make is also a powerful general-purpose tool, and is easily adapted to many 
other uses. 


‘The targets in makefile may include special targets, which trigger program main— 
tenance commands, For example, the target name backup might define commands to 
copy sources to a backup directory; typing make backup backs up the sources. 
Si ‘uses include removing temporary files, building archives, executing test 
suites, and printing hard copies. A makefile is a convenient place to keep all the 


‘commands used to maintain a program. 


‘The following example shows a makefile that defines two special target files, prlatall 
and printnew, to be used with the source files for the program factor.pre. 


4% Macror® consists of © 
# "atod.e",. It oses the standard mathematics (brary 
ff *libr.olb", but it requires no special header f1 
061 = factor.o atod.o 
SRC = factor.c atod.c 
facter.pra + $(0BJ) 

ree -0 factor.peg $(081) 
program to print all the updated source modules 
1 Used to generate the program “factor# 
pringatl: 

ibe S(SRED | pent 

eho junk > prnew 
printnew: 5(083) 

pr 3? | pens 

[Echo junk > printnes 


In this instance, typing the command 


snake princall 
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forces make to generate the target printall rather than the target factor, which is the 
default as it appears first in the makefile, The pr command, with the output piped to 
the parallel port prn:, is then used to print a listing of all files defined by SRC. The 
macro OBJ cannot be used with these commands, because it would trigger the prin— 
ting of the object files, which would not be of much use, The word junk is echoed 
into an empty file, prnew. This new file serves only to record the time the listing is 
printed, This tactic is performed in order to record the time that the listing was last 
generated, so that make will know what files have been updated when you next use 
printnew. 


Typing the command 


make printnew 


forces make to generate the target printnew rather than the default target factor 
printnew prints only the files named in the macro SRC that have changed since any 
Files were last printed. 


Special targets 


‘A few target names haye special meanings to make. The name of each special target 
begins with “ and contains upper-case letters. 


‘Target DEFAULT defines the default commands make uses if it cannot find any 
other way to build a target. The special target .JGNORE in a makefile has the same 
effect as the -1 command line option. Similarly, SILENT has the same effect as the 
=s command line option. 


Errors 


make prints “command exited with status n” and exits if an executed command 
returns an error status, However, it ignores the error status and continues processing 
if the makefile command line begins with 2 hyphen ‘~' or if the make command line 
specifies the -1 ignore errors option. 


make reports an error status and exits if the user interrupts it. It prints “ean't open 
file” if it cannot find the specification file. It prints “Target file ix not defined” o1 
“Don't know how to make Zarget" if it cannot find an appropriate file or commas 
to generate ‘arget. Other possible errors include syntax errors in the specification file. 
macro definition errors, and running out of space. The error messages make prints 
are generally self-explanatory; however, a table of error messages and brief descrip- 
tions of them are given in chapter 4 of this tutorial. 
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Exit status 


make returns a status of 0 if it succeeds and | if an error occurs, For the -q option, it 
returns 0 if the target is up to date and 2 if itis not. 
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4. Summary of make 


‘The following sections summarize the use of make. and present 2 table of the error 
message that can be produced by make. 


Usage 
The usage of make is as follows: 


ake [-dinparst) (-f filename 1 tfimackosdetinition® 7 [target ] 


The argument filenante refers to the file name that accompanies the -f, described 
below, ‘The option "MACRO=defiition” refers to the fact that macros can be defined 
‘on the command line; note that such definitions must be enclosed in quotation marks. 
The option target means that the name of the sarget file within the makefile can be 
changed from the default, which is the file defined in the firsi target line in the 
makefile, 


The makefile may include (1) target line, which names the target file, and (2) a com- 
mand line, which describes the command to be executed to help form a target file, A 
makefile may include more than one target line and more than one command lines for 
each; make's default is to accept and generate the first target in a makefile, but this 
default may be overridden by naming another target file in the make command line, 
A makefile may also name header files to be examined for updating, and may include 
macro definitions and comments. See chapter 2 of this tutorial for details and ex- 
amples, 


Options 

The options to make are as follows: 

-d Debug option, Give verbose printout of all decisions and of the information 
that went into the decisions. This is useful for debugging makefiles. 

-f filename 
File option, This option tells make that filename, rather than makefile, con 


tains the make specifications. If this option does not appear, make uses the 
file makefile in the current directory. 


-i Ignore option. This tells make to ignore error returns from a command and 
continue processing. Normally make exits if a command returns error status, 


-n Test option, This options instructs make only to test a makefile; it suppresses 
‘actual execution of commands. 


=p Print option. Print all macro definitions and target descriptions. 
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q Return a zero exit status if the target files are younger than the source 
modules. No commands are executed. This is the default condition. i 


Rules option, Do not use built-in rules that describe dependencies, 


s Silent option, Do not print command lines when executing them. Commands 
preceded by (@” are not printed, except under the ~n option. 


-t Touch option, Force the dates of targets to be the current time, to bypass ac~ 
tual regeneration, 


Error messages 


The following i-4 able of error menages generated by make, and a brief description 
of each, 


after target or macroname 
A semicolon appeared after a target name or a macro name. This is illegal. 


= in or after dependency 
‘An equal sign ‘=" appeared within or followed the definition of a macro name 
or target file, for example “OBJ=atod.o=factor.o". This is illegal, 


“sf not allowed for name not allowed for name’u’ 
‘A double-colon target line was used illegally, for example, after single-colon 
target line, 


sort in or after dependency list 
‘A triple colon is meaningless to make, and therefore illegal wherever it ap~ 
pears. A single colon may be used only in a target line (which is also called 
the dependency list), and nowhere else 


= without macro name or in token list 
‘An equal sign =" can be used only to define a macro, using the following syn~ 
tax: "MACRO=definition”. An incomplete macro definition, or the ap= 
pearance of an equal sign outside the context of a macro definition, will trig~ 
ger this error message. 
: without preceding target 
‘A colon appeared without a target file name, e. 
Bad macro name 
‘A bad macro name was used. 


Incomplete line at end of file 
‘An incomplete line appeared at the end of the makefile. This is illegal. 


‘Macro definition too tong 
Macro definitions are limited to 200 characters. 


filename”. This is illegal 
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Multiple actions for name 
‘A target is defined with more than one single-colon target line, This is illegal, 


“Multiple detailed actions for name 
‘A larget is defined with more than one single-colon target line. This is illegal. 


Must use *:* for name for name‘u’ 
‘A double-colon target line was followed by a single-colon target line. This is 
illegal. 

Newline after target or macroname 
‘A newline character appears after a target name or a macro name, This is 
illegal. 


Out of core (adddep) 

System problem, Try reducing the size of your makefile, 
Out of space 

System problem. Try reducing the size of your makefile, 
(Out of space (lookup) 

System problem. Try reducing the size of your makefile, 
Syntax error 

“The syntax of a line is Faulty. 
Too many macro definitions 


‘The number of macros you have created exceeds the capacity of your com- 
puter to process them, 
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1, Introduction 
This is a tutorial for the interactive screen editor MicroEMACS. 


‘This tutorial is written for two types of reader: the one who has never used a screen 
editor and needs a full introduction to the subject, and the one who has used a screen 
editor before but wishes to review specific topics. This tutorial is part of the 
documentation for MicroEMACS. MicroEMACS is also summarized in the Lexicon, 
chapter TV of the MicroEMACS manual. 


What is MicroEMACS? 


MicroEMACS is an interactive screen editor. An editor allows you to type text into 
your computer, name it, store it, and recall it later for editing, Interactive means that 
MicroEMACS will accept your editing command, execute it, display the results for 
you immediately, and then wait for your next command. Screen means that you can 
use nearly the entire screen of your terminal as a writing surface: you can move your 
cursor up, down, and around your screen to create or change text, much as you move 
your pen up, down, and around a piece of paper. 


‘These features, plus the others that will be described in the course of this tutorial, 
make MicroEMACS s tool that is powerful, yet easy to use. You can use 
MictoEMACS to create or change computer programs, essays or letters, or any other 
type of text file. 


‘The present version of MicroEMACS was adapted by Mark Williams Company from a 
public-domain program written by David G. Conroy, This tutorial is based on the 
descriptions in his essay MicroEMACS: Reasonable Display Editing in Little Com~ 
puters. MicroEMACS is derived from the mainframe display editor EMACS, which 
was created at the Massachusetts Institute of Technology by Richard Stallman. 
EMACS is popular among persons who work with computers for a living; it is the 
parent or grandparent of a number of well-known word processors. 


Structure of the tutorlal 


‘This tutorial has two parts, Part 1, which includes chapters 2 through 9. covers basic 
editing with MicroEMACS. Most users will find that these chapters contain all the 
information they need 10 use MicroEMACS productively, Part 2, which includes 
chapters 3 through 16, describes advanced editing — editing techniques that exploit 
the full power of MicroEMACS, These advanced techniques include the use of ar- 
guments with MicroEMACS's commands, multiple windows and buffers, and 
keyboard macros, The Lexicon contains 2 summary of all of MicroEMACS's com- 
mands. 
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Do the exercises 


‘The following chapters include exercises that illustrate each topic being discussed. 
‘These exercises will help you understand exactly how each feature works. We recom- 
mend that you type each exercise as you come to it in the text. Even if you under~ 
stand the concepts being discussed, working the exercises will reinforce the lesson and. 
will help you grow comfortable in using MicroEMACS, 
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2. Basic Editing 


‘MicroEMACS is an interactive screen editor. 


Interactive means MicroEMACS accepts s command from you, executes it, displays 
the result on your terminal immediately, and then waits for your next command, 


Screen means MicroEMACS allows you to use nearly the entire screen of your ter— 
jninal as a writing surface, You can move your cursor up, down, and around the 
screen to enter text or make changes, much as you move your pen up, down, and 
around a sheet of paper. 


‘The first half of this tutorial, chapters 2 through 9, describes basic editing with 
MicroEMACS. Mastering the commands described in the next few subsections wil 
allow you to create a document, store it, and edit it thoroughly, Advanced techn 
ques, such as assembling text from several buffers, using windows, and using ar- 
uments, will be covered in the second half. 


Keystrokes—<ese>, <ctrl> 
‘The MicroEMACS commands use control characters and meta characters, 


Control characters use the contro key, which is marked Control on your keyboard; 
meta characters use the escape key, which is marked Ese. 


On your keyboard, the escape key is located in the upper left-hand corner of the 
keyboard, ‘The control key is also located at the left end of your keyboard, just to the 
left of the "A’ character key. 

‘To see how the control and escape keys actually work, consult any reference manual 


that describes the ascii table. To use them with MicroEMACS, however, only re- 
quires that you key them correctly. 


Control works like the shift key: you hold it down while you strike the ather key. 
Here, this will be represented with a hyphen; for example, control X will be shown as 
follows: 


cere 
‘The ese key, on the other hand, works like an ordinary character. You should strike 


it first, then strike the letter character you want, Escape character codes will not be 
represented with a hyphen; for example, escape X will be represented a5: 


esx 
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Becoming acquainted with MicroEMACS, 


Now you are ready for a few simple exercises that will help you get a feel for how 
MicroEMACS works. 


‘To begin, use the mouse to invoke the Mark Williams micro-shell msh, If you do not 
yet know how to use msh, see the section on msh in chapter IT of the MicroEMACS, 
manual. As soon as the prompt for msh has appeared in the upper left-hand corner 
of your screen, type 


ne sample 


Within a few seconds, your screen will have been cleared of writing, the cursor will 
be positioned in the upper left-hand corner of the screen, and a command line will 
appear at the bottom of your screen. 


Now type the following text. If you make a mistake while typing, just backspace over 
it and retype the text. Press the carriage return key, which is inbelled Return, after 
each line: 


There {nothing which has yet been contrived by 
n, by which to much happiness |8 produced as by 
00d tavern or inn. 


Notice how the text appeared on the screen character by character as you typed it, 
much as it would appear on a piece of paper if you were using a typewriter. 


Now, type <etrl-X><etrl-S>; that is, type <etrl-X>, and then type <etrl-S>. It does 
‘not matier whether you type capital or lower-case letters, Notice that this message 
has appeared at the bottom of your screen: 


Wrote 3 (ines) 


‘This command has permanently stored, or saved, what you typed. The text will now 
be preserved until you use the rm command to delete it. 


Type the next few commands, which demonstrate some of the tasks that 
MicroEMACS can perform for you. These commands will be explained in full in the 
sections that follow; for now, it is enough for you to get a feel for how MicroEMACS. 
works. 


Type <ese><. Be sure that you type a less-than symbol *<’, instead of = comma, 
Notice that the cursor has returned to the upper left-hand corner of the screen, Type 
-<ese>F. The cursor has jumped forward by one word, and is now between the words 
There and is. Type <etrl-N>. Notice that the cursor has jumped to the next line, and 
is now under the letter b of the word by. Type <ctrl-A>. The cursor has jumped to 
the beginning of the second line of your text. 
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Now, type <ctrl-K>, The second line of text has disappeared, leaving an empty 
space. Type <ctrl-K> again, The empty space where the second line of text had been 
‘has now disappeared, 


‘Type <ese>>, Be sure to type a greater-than symbol ‘>’, not a period. The cursor has 
jumped to the space just below the last line of text. Now type <ctrl-Y>. The text 
that you erased a moment ago has now been restored. 


By now, you should be feeling more at ease with typing Micro—EMACS's control and 
escape codes. ‘The following sections will explain what these commands mean. For 
now, exit from MicroEMACS by typing <ctrl-X><ctel-C>, and when the message 


uit. tyra? 


appears, type y. This will return you to msh, 


Before you begin 


There are one or two potential sources of difficulty that you should watch for as you 
begin to work with MicroEMACS, 


Note that MicroEMACS may be overwhelmed if you attempt to edit an extremely 
large file, If your file proves to be too large, either when it is loaded or while you are 
Working on it, you will see the following message: 


File too Large for available mecory! 


When this happens, you must exit from MicroEMACS to msh by typing <etrl~ 
X><etrl-C>; if you use any other command in an attempt to save the changes you 
mnde to your text, you will corrupt your original file. Exiting to msh will be covered 
in the next few pages. 


Three sample texts have been included with MicroEMACS. They are called text1.m, 
text2.m, and text3.m, Before you begin, be sure to make working copies of these 
texts, $0 that if an accident were to occur while you were working on this tutorial the 
master copies of the sample texts will still be preserved. 

‘You should use the ep command to copy the files to the following file names: text!.m 
10 textl, fext2.m to text2, and text3.m to text3, If you do not know how to use the 
ep command, see the entry for it in the Lexicon. 


If you are going to edit a large text, MicroEMACS may take a few seconds to load it 
into memory. 


‘You will know MicroEMACS set up and ready to go when the following message ap- 
pears at the bottom of your screen: 
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{Read %« Lines? 


where Xx stands for the number of lines in your text file. If you are creating a new 
text file, MicroEMACS will send you this message: 


Dhow Filed 


Beginning a document 
You are now ready to invoke MicroEMACS and create a text file. Type the following 
command line, which tells MicroEMACS that you wish to edit the text called textl: 

te text 
This text hns Been included with your MictoEMACS compiler; there is no need to 
retype it, 


‘The computer will take a moment to set up the MicroEMACS program. As soon as it 
does so, the following text will appear on your scree! 


From "Life on the Mississippi 
T know how s prize wetermeton looks shen It fs sunning 
it fat roturdity among the pumpkin vines; I know how to tell 
ten It fn ripe without plugging” ft; 1 krow how inviting 
{t looks when it ia cooling Iteelt (na tub of water under 
the bed, waiting: 1 kro how it looks when it (ies on the 
‘able In the sheltered great floor space between house and 
Kitchen, and the chileren gathered for the sacritice onc 
their mouths watering; 1 know the crackling sound it makes 
When the carving knife enters its end, ard! can see the 
Uplit fly slang In front of the blede’or the knife cleaves 
ts May to the other end; I can see (ts halves fall apart 
tnd display the rich red meat ard the Black seeds, and the 
heart tending up, a Laury fit the elect; 1 know how a 

‘boy looks behind a yard-Lang stice of that melon, and 1 

know how he feels; for 1 have been there. 


When you type the MicroEMACS command and a file name, MicroEMACS copies. 
that text file into a special area in your computer to make it available for editing. If 
‘you were creating a new text, as you did earlier with the text called sample, the screen 
‘would have appeared blank. 


In addition to this text appearing on your screen, your cursor moved to the upper 
Jeft-hand corner of the screen, and the status line appeared near the bottom of your 
screen as follows: 
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ST WicroeMACS V1.2 ++ texth -- Files textt - 


‘The word to the left, MicroEMACS, is the name of the program. The next word, 
shown here as V1.2, is the version number. It may be different with your copy of 
Mark Williams C. The word in the center, textl, is the name of the tu/fer that you 
are using, (What a buffer is and how it is used will be covered later.) The name to the 
right is the name of the text file that you will be editing. 
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3, Moving the Cursor 


Now that you have created a text file, you will want to edit it, The first step is to 
earn to move the cursor. Try these commands for yourself as they are described in 
the following pages. That way, you will quickly acquire a feel for handling 
MicroEMACS's commands. You can use your arrow keys with MicroEMACS. The 
arrow keys are found on the pad to the right of the alphabetic keyboard. The arrow 
keys move the cursor in the direction indicated (Ieft, right, up, or down); this tutorial, 
however, will refer primarily to the basic cursor movement commands displayed 
below: 


<ctrl-B> Move back 1 space 
<ese>B Move back | word 
<ctrl-E> Move to end of line 
<ctrl-F> Move forward 1 space 
<ese>F Move forward | word 
<ctrl-A> Move to beginning of line 
<ctrl-P> Move to previous line 
<ctrl-N> Move to next line 
<etrl-V> Move forward | screen 
<escoV Move back | screen 
seser< Move to beginning of text 
<ese>> Move to end of text 


Moving the cursor backwards 


The first set of commands move the cursor backwards. First, type the end of text 
command <ese>> to move the cursor to the bottom of the text. Be sure to type @ 
greater-than symbol ">", not a period. 


‘Type the backspace command <ctrl-B>. This is equivalent to pressing the left arrow 
key. As before, it does not matter whether the letter “B" is upper case or lawer case. 
Note that the cursor is now located just to the right of the period in your last line of 
text. Type <ctrl-B> again. The cursor has moved one space to the ieft, and now is 
directly over the period. 


Type <ese>B. The cursor has moved one word to the left, and is now over the letter t 
of the word there. Type the beginning of line command <etrl-A>. The cursor has 
Jumped to the beginning of the line, and is now over the letter k of the word know. 
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Moving the cursor forwards 


Now practice moving the cursor forwards, Type the forward command <ctrl-F>. 
This is equivalent to pressing the right arrow key. Note that the cursor has moved one 
space 10 the right, and now is over the letter n of the word know. Type <esc>F. The 
cursor has moved one word to the right, and now is over the space between the words 
know and how. 


Type the end of line command <ctrl-E>. The cursor has jumped to the end of the 
fine, and once again is resting to the right of the period. 


From tine to line 


‘The next two commands move the cursor up and down the screen. Type the previous 
line command <ctrl-P>. Note that the cursor has jumped from its position to the 
right of the period on the last line of your text, to being over the second letter t of the 
word that in the previous line. 


Continue to type <etrl-P> until the cursor reaches the top of the screen. This has the 
same effect as if you typed the up arrow key. Note that as you reached the first tine 
in your text, the cursor jumped from under the letter 1 of the word it on the second 
line, to being just right of the colon on the first line of text. When you move your 
cursor up or down the screen, MicroEMACS will try to keep it at the same position 
within each line. If the line to which you are moving the cursor is not long enough to 
have a character at that position, MicroEMACS will move the cursor to the end of the 
line. 


Now, practice moving the cursor back down the screen. Type the next line command 
<ctrl-N>, This has the sume effect as pressing the down arrow key. Note that when 
the cursor jumped to the next line, it returned to under the letter 1 of the word it. 
MicroEMACS remembered the cursor’s position on the line, and returned the cursor 
there when it jumped toa line long enough to have a character in that position, 


Continue pressing <etrl-N>. The cursor will move down the screen, until it 
the bottom of your text, 


reaches 


Moving up and down by a screenful of text 


‘The next two cursor movement commands allow you to roll forward or backwards by 
one screenful of text. 


If you are editing a file with MicroEMACS that is too big to be displayed on your 
sereen all at once, MicroEMACS will display the file in screen-sized portions (22 lines 
ata time). The view commands <ctrl-V> and <ese>V allow you to roll up or down by 
fone screenful of text at a time. 
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‘Type. <ctrl-V>_ Note that your scroon becomes empty. This is because you have 
rolled forward by the equivalent of one screenful of text, or 22 lines; however, be- 
cause the text in this example is only 16 lines long, rolling forward 22 lines just 
empties the screen, 


‘Now, type <ese>V. Notice that your text rolls back onto the screen, and your cursor. 


is positioned in the upper left-hand corner of the screen, over the letter F of the word 
From. 


Moving to beginning or end of text 


The last two cursor movement commands allow you to jump immediately to the 
beginning or end of your text. 


The end of text command <esc>> moves the cursor to the end of your text. Type 
<esce>. Be sure to type a greater-than symbol ">" 


The heginning of text command <esc>< will move the cursor back to the beginning of 
your text. Type <esc><, Be sure (0 type a less-than symbol “<’. Note that the cursor 
has jumped back to the upper left-hand corner of your screen. 


These commands will move you immediately to the beginning or the end of your 
text, regardiess of whether the text is one page long or 20. 


Cursor movement strategy 

When you edit a large text, you must move the cursor often. This can be very time— 

consuming, Three rules will help you save time by moving the cursor efficiently. 

1. Plan your cursor movements so that you reach your target with a few keystrokes, 
if possible. 

2. If you are a good typist, avoid using the <ese> key if possible, because using the 
<<esc> key usually forces you to lift your left hand from the home position. 


3, ‘Try not to use the arrow keys if possible. Using the arrow keys moves your 
hands out of the home position, which slows your typing and increases the 
chance that you will replace them on the keyboard in the wrong position, 


‘Try the following exercises to sharpen your command of cursor movement. Each ex- 
ercise is followed by its solution. Do not look at the solution until you have at least 
attempted to solve the protlem. The exercises should be done in order, because each 
one builds on the ones that came before, 


1. Your cursor should be in the upper left-hand corner of the screen. If it is not, 


type <ese><, Now, move the cursor to the space just before the word children in line 
8-you should be able to do it with ten commands, 
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Soh 


sn: Type <ctrl-N> seven times, then type <ese>F three times. 


2, Move the cursor to the letter m of the word knife in line 10—you should be able to 
do it with four commands. 


Solution; Type <ctrl-N> twice, then <ctrl-F> twice, 


3. Move the cursor to the right of the period on line 16~you should be able to do it 
with two commands, 


Solution: Type <ese>>, then type <ctrl-B>. 


4. Move the cursor to the space after the word fall on line 12—you should be able to 
do it with six commands. 


Solution: Type <ctrl-P> four times, then type <esc>F twice. 


5, Move the cursor to the letter k of the word kitchen 
to do it with five commands, 


Solution: Type <ctrl-A>, then type <ctrl-P> four times. 


6. Finally, move the cursor to under the letter M of the word Mississippi on line 
1-you should be able to do it with three commands, 


line &you should be able 


Solution: Type <ese><, type <etrl-E>, then type <ese>B. 


Saving text and quitting 


If you do not wish to continue working at this time, you should save your text, and 
then quit. 


It is good practice to save your text file every so often while you are working on it, 
then, if an accident occurs, such as a power failure, you will not lose all of your work, 
You' can save your text with the save command <ctel-X><ctrl-S>. Type <ctrl- 
X>-etrl-S>—that is, first type <etrl-X>, then type <ctrl-S>, Note that at the bottom 
of your screen the following message has appeared: 


[urote 16 Lines} 


The test file has again been saved to your computer’s memory. Note, too, that 
MicroEMACS will send you messages from time to time; the messages enclosed in 
square brackets ‘{' ‘J’ are for your information, and do not necessarily mean that 
something is wrong. To exit from MicroEMACS, type the quit command <cirl- 
X><etrl-C>. This will return you to msh, 
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4, Killing and Deleting 


Now that you know how to move the cursor, you are ready to edit your text. To 
return to MicroEMACS, type the command: 


ne text 


Within a moment, text1 will be restored to your screen. 


By now, you probably have noticed that MicroEMACS is always ready to insert 
material into your text; unless you use the <etrl> or <exe> keys, Mi 

sume that whatever you type is meant to be text and will insert it onto your screen 
where your cursor is positioned. 


The simplest way to erase text is simply to position the cursor to the right of the text 
you want to erase and backspace over it. MicroEMACS, however, has a set of com= 
mands that allow you to erase large amounts of text easily, These commands kill and 
delete; the distinction is important, and will be explained in a moment. The following 
display summarizes these commands: 


<etel=D> Delete | character to the right 
<ese>D. Kill | word to the right 

<del> Delete | character to the left 
<etrl-H> Delete 1 character to the left 
<ese><del> Kill | word to the left 
<ese><ctrl-H> Kill! word to the left 
<etrl-K> Kill rest of line 

cetel-Y> Yank back (restore) killed text 


Deleting versus killing 


It is important to distinguish between killing and deleting. When text is deleted. it is 
erased completely; however, when text is killed, it is moved into a temporary storage 
area elsewhere in the computer. This storage area is erased when you move the cursor 
and then kill additional text, Until then, however, the killed text is saved. This 
aspect of killing allows you to restore text that you killed accidentally, and it also 
allows you to move or copy portions of text from one position to another. 
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Erasing text to the right 


‘The first two commands to be presented erase text to the right. 


‘Type the delete command <ctrl-D>. Note that the letter F of the word From has been 
erased, and the rest of the line has shifted one space to the left, 


Now, type <esc>D. The rest of the word From has been erased, and the line has 
shifted three spaces to the left, Note that the cursor is positioned at the space before 
the string: 


mite 


‘Type <esc>D again. The string “Life has vanished along with the space that preceded 
it, and the line has shifted six spaces to the left. 


Note that <etrl-D> deletes text, but <esc>D kills text. 


MicroEMACS is designed so that when it erases text, it does so beginning at the left 
edge of the cursor, You should imagine that an invisible vertical bar separates the 
cursor from the character immediately to its left; as you enter the various kill and 
delete commands, this vertical bar moves to the right or the left with the cursor, and 
erases the characters it touches. Therefore, if you wish to erase a word but wish to 
keep both spaces around it, position your cursor directly over the first character of 
the word and strike <ese>D. If you wish to erase a word and the space before it, 
position the cursor at the space before you strike <ese>D, so that the invisible vertical 
bar sweeps away the space at which the cursor is positioned, as well as the word that 
follows, 


Erasing text to the left 


You can erase text to the /e/t by using the Delete key. This key is located just below 
the backspace key on the right side of the alphabetic keyboard. Be sure to note where 
it is, because it is most useful, You can also erase text to the left with the command 
<ctrl-H>. 


To see how to erase text to the left, first type the end of line command <ctrl-E>; this 
will move the cursor to the right of the colon on the first line of text. Type <del>. 
‘Note that the colon has vanished. 
Type cese><del>. The string 

wisatesipr# 


has disappeared, and the cursor has moved to the second space following the word 
the. 
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Move the cursor four spaces to the left, so that it is over the letter t of the word the. 
Type <ese><del>, The word on has vanished, along with the space that was im 
mediately to the right of it. As before, these commands erased text beginning im— 
mediately to the left of the cursor. The <esc><del> command can be used to erase 
words throughout your text, 


If you wish to. erase a word to the left yet preserve both spaces that are around it, 
position the cursor at the space immediately to the right of the word and strike 
<esco<del>. If you wish to erase a word to the left plus the space that immediately 
follows it, position the cursor under the first letter of the next word and then strike 
<esc><del>. 


Note that typing <del> deletes text, but typing <esc><del> kills text. 


Erasing lines of text 


Finally, the following command erases a line of text: the kil! command <ctrl-K>. 
‘This command erases a line of text, beginning from immediately to the left of the 
cursor. 


To see how this works, move the cursor to the beginning of line 2. Now, strike <ctrl= 
K>, All of line 2 has vanished, and been replaced with an empty space. Strike <ctrl- 
K> again. The empty space has vanished, and the cursor is now positioned at the 
beginning of what used to be line 3, over the letter I of the word its, 


As its name implies, the <etrl-K> command kills the line of text. 


‘anking back (restoring) text 


Remember that when material is killed, MicroEMACS has temporarily stored it else 
where, Thus, text that has been killed can be returned to the screen by using the 
yank back command <ctrl-Y>. Type <ctrl-¥>. All of line 2 has returned; the cursor, 
however, remains over the letter i of its in line 3. 


Killing and deleting—exercises 


To fix these distinctions in your mind, perform the next few exercises. Work the ex- 
ercises in order, as each exercise builds on the ones that came before it, and do not 
look at the solution until you have at least tried to solve the problem. 


Before you begin, move your cursor back to the upper left-hand corner of your 
screen by typing <esc>< 


1. Erase the word sheltered in line 7 and the space that follows it. 
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Solution: To move the cursor to the correct position, type <ctri-N> six times; type 
‘<ese>F four times; and type <etrl-F> once. Then type <ese><del>. 


2, Erase the word children in line 8, and the space that precedes it. 


Solution: To move the cursor to the correct position, type <ctrl-N>, then type 
<esc>F, Type <ese>D. 


3. Erase line 4. 

Solution: To move cursor, type <ctrl-P> four times, then <etrl-A>_ Type <ctrl-K>. 
4, Yank back line 4. 

Solution; Type <etrl-Y>. 


Quitting 


When you are finished, do not save the text. If you do so, the undamaged copy of the 
text that you made earlier will be replaced with the present changed copy. Rather, 
use the quit command <ctrl-X><ctrl-C>. Type <ctrl-X><etrl-C>. On the bottom of 
‘your screen, MicroEMACS will respond: 


ute ty/nt? 


Reply by typing y and a carriage return. If you type m, MicroEMACS will simply 
return you to where you were in the text. MicfoEMACS will then return you to msh, 
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5. Block Killing and Moving Text c 


‘As noted above, text that is killed is stored temporarily within the computer, Killed 
text may be yanked back onto your screen, and not necessarily in the spot where it 
‘was originally killed. This feature allows you to move text from one position to 
another. 


‘The following table summarizes the commands used to kill a block of text and m 


<etrl-K> Kill text to end of line 


<ctrl-@> Set mark 
<ctrl-W> Kill block of text 


<ctrl-Y> ‘Yank back text 


) 
Moving one fine of text 


To test these commands, invoke MicroEMACS for the text text by typing the 
following command: 

ne text? 
When MicroEMACS appears, the cursor will be positioned in the upper teft-hand 
corner of the screen, 


To move the first line of text, begin by typing the Aill command <ctrl-K> twice, 
Now, press <ese>>, 10 move the cursor to the bottom of text, Finally, yank back the 
line by typing <ctrl-Y>. The line that reads 


Fron "(fe on the Mississipp{: 


is now at the bottom of your text, 
Note that your cursor has moved to the point after the line you yanked back. 


Multiple copying of killed text 


When text is yanked back onto your screen, it is not deleted from within the com=_ 
puter. Rather, it is simply copied back onto the screen, This means that killed t 
can be reinserted into the text more than once, To see how this is done, return to the 
top of the text by typing <esc><. Then type <etrl-Y>. The line you just killed no 
appears twice on your screen. 
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Note that the killed text will not be erased from its temporary storage until you move 
the cursor and then kill additional text. If you kill several lines or portions of lines in 
a row, all of the killed text will be stored in the buffer; if you are not careful, you 
may yank back a jumble of accumulated text. 


Kill and move & block of text 


If you wish to kill a block of text, you can either type the kill command <etel-K> 
repeatedly to kill the block one line at a time, or you can use the Afock kill command 
<ctrl-W>. To use this command, you must first set a mark on the screen, an invisible 
character that acts as a signal to the computer. The mark is set with the mark com- 
mand <ctrl-@>. 


Once the mark is set, you must move your cursor to the other end of the block of text 
you wish to kill, and then strike <etrl-W>. The block of text will be erased, and will 
be ready to be yanked back elsewhere, 


Try this out on textl, Type <esc>< to move the cursor to the upper left-hand corner 
of the screen, Then type the set mark command <ctrl-@>. By the way, be sure to 
type a'@’, not a ‘2’, MicroEMACS will respond with the message 


hark sey 


at the bottom of your screen, Now, move the cursor down four lines, and type <etrl- 
We. Note how the block of text you marked out has disappeared. 


Move the cursor to the bottom of your text. Type <ctrl-Y>. The killed block of text 
has now been reinserted, 


When you yank back text, be sure to position the cursor at the exact point where you 
want the text to be yanked back, This will ensure that the text will be yanked back in 
the proper place. 


To try this out, move your cursor up four lines, Be careful that the cursor is at the 
beginning of the line. Now, type <ctrl-Y> again, Note that the text reappeared above 
where the cursor was positioned, and that the cursor was not moved from its position 
at the beginning of the line—which is not what would have happened had you 
positioned it in the middle or at the end of a line. 


Although the text you are working with has only 16 lines, you can move much larger 
portions of text, using only these three commands, Remember, too, that you can use 
this technique to duplicate large portions of text at several positions, to save yourself 
considerable time in typing and reduce the number of possible typographical errors. 
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6. Capitalization and Other Tools 


‘The next commands perform a number of useful tasks that will help with your 
editing. They are as follows: 


<eseoC Capitalize a word 
<esc>L Lowercase a word 
<esc>U Uppercase a word 
<etrl-T> ‘Transpose characters 
<ctrl-L> Redraw screen 


<ctrl-X>F Set word wrap 


Before you begin this section, destroy the old text on your screen with the quit com- 
mand <ctrl-X><etrl-C>, and read into MicroEMACS a fresh copy of the text, as you 
did earlier. 


Capitalization and lowercasing 


MicroEMACS has several commands that can automatically capitalize words or make 
them all upper case or lower case. 


Move the cursor to the letter w of the word watermelon on line 2, Type the capitalize 
command <ese>C, The word is now capitalized, and the cursor is now positioned at 
the space after Move the cursor back so that it is over the letter m in Watermelon. 
Press <esc>C again. The word changes WaterMelon. When you press <esc>C, 
MicroEMACS will capitalize the first letter the cursor meets. 


MicroEMACS can also change a word to all upper case or all lower case. (There is, 
very little need for a command that will change only the first character of an upper- 
case word to lower case, so it is not included.) 


‘Type <ese>B to move the cursor so that it is again to the left of the word WaterMelon, 
It does not matter if the cursor is directly over the W or at the space to its left; as you 
will see, this mean that you can capitalize or lowercase a number of words in a row 
without having to move the cursor. 


‘Type the uppercase command <ese>U. The word is now spelled. WATERMELON, 
‘and the cursor has jumped to the space after the word. 


Again, move the cursor to the left of the word WATERMELON. Type the lowercase 
command <ese>L. The word has changed back to watermelon. Now, move the cursor 
to the left of the string 


mite 
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on line |. Type <ese>L once again, Note that the quotation mark is not affected b: 
the command, but the letter L is naw lower case. <esc>L not only shifts a word that is 
all upper case to lower case: it can also un-capitslize a word. 


Note that the uppercase and lowercase commands will stop at the first point of 
punctuation they encounter after the first letter they find; this means that, for ex- 
ample, to change the case of a word with an apostrophe in it you must type the ap- 
propriate command twice. 


‘Transpose characters 


MicroEMACS allows you tp reverse the position of two characters, or tranypose them, 
with the transpose command <ctrl-T>. 


Type <ctrl-T>. ‘The character that is under the cursor has been transposed with the 
character immediately to its left, Type <etrl-T> again, The characters have returned 
to their original order, 


Screen redraw 


Occasionally, the characters on your screen may become mixed up, due to an un- 
foreseen complication beyond your control. The redraw screen command <etrl-L> 
‘will redraw your screen to the way it was before it was scrambled, 


Type <etrl-L>. Notice how the screen flickers and the text is rewritten. Had your 
screen been spoiled by extraneous material, that material would have been erased and 
the original text rewritten. 


The <etrl-L> command also has another use: you can move the line on which the 
cursor is positioned to the center of the screen. If you have a file that contains more 
than one screenful of text and you wish to move a particular line to the center of the 
screen, position the cursor on that line and type <ctrl-U><etrl-L>. Immediately, the 
screen Will be rebuilt with the line you were interested in positioned in the center. 


Word wrap 


Although you have not yet had much opportunity to use it, MicroEMACS will 
automatically wrap around text that you are typing into your computer. Word wrap- 
ping is controlled with the word wrap command <ctrl-X>F. 


To see how the word wrap command works, first move to the end of the text file by 
typing the end of file command <ese>>. Now type the following text; however, do 
hot type any carriage returns: 
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‘A cucinber should be well sticed, 
and dressed with pepper and vinegsr, 
Grd then thrown out, as good 

for nothing. ; 


When you reached the edge of your screen, a dollar sign was printed and you were 
allowed to continue typing. MicroEMACS accepted the characters you typed, but it 
placed them ata location beyond the right edge of your screen. 


Now, move to the beginning of the next line and type <etrl-U>. MicroEMACS will 
reply with the message: 


ara: & 
‘Type 30. The line at the bottom of your screen now appears as follows: 
Avge 30 


(The use of the argument command <ctrl-U> will be explained in full in chapter 11.) 
Now type the word-wrap command <etrl-X+F. MicroEMACS will now say at the 
bottom of your screen: 


rap at column 30) 


‘This sequence of commands has set the word-wrap function, and told it to wrap to 
the next line all words that extend beyond the 30th column on your screen, 


To test word wrapping, type the above text again, without using the carriage return 
key. When you finish, it should appear as follows: 


A eueunber should be well 
Uiced, and dresued with 

Pepper’ and vinegar, and then 
thrown out, es goed for nothing, 


MicroEMACS automatically moved your cursor to the next line when you typed 
space character after the 30th column on your screen. 


‘The word wrap feature automatically moves your cursor to the beginning of the next 
line once you type past a preset border on your screen; when you first enter 
MicroEMACS, that limit is automatically set at the first column, which in effect 
‘means that that word wrap has been turned off. P 


When you type prose, for a report or a letter of some sort, you probably will want to, 
set the border at the 65th column, so that the printed text will fit neatly onto @ sheet 
of paper. If you are using MicroEMACS to type in a program, however, yol 
probably will want to turn off word wrapping, so you do not accidentally introduce 
carriage returns into your code, 
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If you wish to fix the border at some special point on your screen but do not wish to 
go through the tedium of figuring out how many columns from the left it is, simply 
position the cursor where you want the border to be, type <ctrl-X>F, and then type 2 
carriage return. When <ctrl-X>F is typed without being preceded by a <ctri-U> 
command, it sets the word-wrap border at the point your cursor happens to be 
positioned. When you do this, MicroEMACS will then print a message at the bottom 
of your terminal tells you where the word-wrap border is now set. 


If you wish to turn off the word wrap feature again, simply set the word wrap border 
at some very large number, such as 5,000. 
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7. Search and Reverse Search 


When you edit a large: text, you may wish to change particular words or phrases. To 
do this, you can roll through the text and read each line to find them; or you can have 
MicroEMACS find them for you. The following summarizes the MicroEMACS 
search commands: 


<ctrl-S> Search forward incrementally 
<esoS Search forward with prompt 
<cirl-R> Search backwards incrementally 
<esc>R Search backwards with prompt 
<ctrl-G> Cancel a search command 


Before you continue, close the present file by typing <ctrl-Z>; now reinvoke the 
editor with the file text1 by typing 


re toxtt 


‘The following sections will perform some exercises with this file. 


Search forward 


As you can see from the display, MicroEMACS has two ways to search forward: in- 
crementally, and with a prompt, 


An incremental search is one in which the search is performed as you type the charac 
ters. To see how this works, first, type the beginning of text command <ese>< to 
move the cursor to the upper left-hand corer of your screen. Now, type the 
incremental search command <etrl-S>- MicroEMACS will respond by prompting 
with the message 


(-search forward: 
at the botiom of the screen, 


We will now search for the word way. Type the letter w. Note that the cursor has 
jumped to the first word that has a w, which is watermelon. Now, type a, The cursor 
moves forward one space, because watermelon also has wa in it. Note how the mes- 
sage at the bottom of the screen has also changed to reflect what you have typed. 


Now type y, The cursor has jumped ahead to the word way. Finally, type <ese>. 
‘MicroEMACS will reply with the message 


‘Boned 
which 


icates that the search is finished, 
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If you attempt an incremental search for word that is not in the file, MicraEMACS 
will find as many of the letters as it can, and then give you an error message. For ex- 
ample, if you tried to search incrementally for the word ways, MicroEMACS would 
‘move the cursor to the Word way, when you typed ‘s’, it would tell you 


fe 


fing i-search forward: ways 


With the promp! search, however, you type in the word all at once, To see how this 
works, tyne <ese><, to return to the top of the file, Now, type the prompt search 
command <ese>S, MictoEMACS will respond by prompting with the message 


Search way]: 


at the bottom of the screen, The word ways is shown, because that was the last word 
for which you searched, and so it is kept in the search buffer. 


‘Type in the words been there, then press the carriage return. Notice that the cursor 
has jumped to the period after the word there in the last line of your text, 
MictoEMACS searched for the words been there, found them, and moved the cursor 
to them. 


If the word you were searching for was not in your text, or at least was not in the 
portion that fies between your cursor and the end of the text, MicroEMACS would 
not have moved the cursor, and would have displayed the message 


Wor found 


at the bottom of your screen, 


Reverse search 


The search commands, useful as they are, can only search forward through your text. 
To search backwards, use the reverse search commands <ctrl-R> and <ese>R. These 
work exactly the same as their forward-searching counterparts, except that they 
search toward the beginning of the file rather than toward the end, 


For example, type <esc>R. MicroEMACS will reply with the message 
Reverse search (been therel: 


at the bottom of your screen, The words in square brackets are the words you entered 
earlier for the search command; MicroEMACS remembered them. If you wanted to 
search for been there again, you would just press the carriage return, For now, 
however, type the word watermelon and press the carriage return, 
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Notice that the cursor has jumped so that it is under the letter w of the word water~ 
melon in line 2, When you search forward, the cursor will move to the space a/ter the 
word you are searching for, whereas when you reverse search the cursor will be 
moved to the first letter of the word you are searching for. 


Cancel a command 


As you have noticed, the commands to move the cursor or to delete or kill text all ex= 
ecute immediately. Although this speeds your editing, it also means that if you type a 
command by mistake, it executes before you can stop 


‘The search and reverse search commands, however, wait for you to respond to their 
prompts before they execute. If you type <ese>S or <esc>R by accident, 
MicroEMACS will interrupt your editing and wait patiently for you to initate a search 
that you do not want to perform. You can evade this problem, however, with the 
ance! command <etr-G>. This command tells MicroEMACS to ignore the previous 
command. 


‘To see how this command works, type <ese>R. When the prompt appears at the bot 
tom of your screen, type <ctrl-G>. Three things happen: your monitor chimes, the 
characters “G appears at the bottom of your screen, and the cursor returns to where it 
in your text was before you first typed <esc>R. The <ese>R command has been can- 
celled, and you are free to continue editing. 


If you cancel an incremental search command, <etrl-S> or <esc-S>, the cursor will 
return to where it was before you began the search. For example, type <esc>< (0 
return to the top of the file. Now type <ctrl-S>, to begin an incremental search, and 
type w. When the cursor moves to the w in watermelon, type <ctrl-G>. The bell will 
ring, and your cursor will be returned to the type of the file, which is where you 
began the search. 
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8. Saving Text and Exiting 


‘The last get of basic editing commands allow you to save your text and exit from the 
MicroEMACS program. They are as follows: 


<ctrl-X>-<etrl-S> Save text 
<ctrl-X><etrl-W> Write text toa new file 
<ctrl-Z> Save text and exit 
<ctrl-X><et-O Exit without saving text 


‘You have used two of these commands already: the save command <ctrl-X><ctrl-S> 
and the quit command <etrl-X><ctrl-C>, which respectively allow you to save text or 
to exit from MicroEMACS without saving text. (Commands that begin with <ctrl-X> 
are called extended commands; they are used frequently in the advanced editing to be 
covered in the second half of this tutorial.) 


Write text to a new file 


If you wish, you may copy the text you are currently editing to a text file other than 
the one from which you originally took the text. Do this with the write command 
<ctrl-X><etrl-W>. 


To test this command, type <ctrl-X><ctrl-W>. MicroEMACS will display the 
following message on the bottom of your screen: 


Write file: 


MicroEMACS ig asking for the name of the file to which you wish to write the text, 
Type twain, MicroEMACS will reply: 


[wrote 21 Lines) 


The 16 lines of your text have been copied to a new file, called twain, Note that the 
status line at the bottom of your screen has changed to read as follows 


s+ ST MICrOEMAGS V1.2 -> text) o> Filer tain 


The significance of the change in file name will be discussed in the second half of this 
tutorial, 


Before you copy text to-a new file, be sure that you have not selected a file name that 


ig already being used. f you do, whatever is being stored under that file name will be 
erased, and the text created with MicroEMACS will be stored in its place. 
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Save text and exit Y 


Finally, the store command <ctrl-Z> will save your text and move you out of the 
MicroEMACS program. To see how this works, watch the bottom line of your ter 
minal carefully and type <etrl-Z>, and then the msh prompt reappears, 
‘MicroEMACS has saved your text, and now you can issue commands directly to msh. 
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9. Rasie Faiting—Conclusion and Summary 


This concludes the presentation of MicroEMACS's basic commands. The second half 
of this tutorial will introduce you to the advanced features of the MicroEMACS in- 
teractive screen editor, 


This section introduced the basics of using an interactive screen editor, and presented 
the basic MicroEMACS editing commands. 


If you have mastered the commands and techniques in the first half of this tutorial, 
you may have no need to work any further, because you now can create a file, edit it, 
store it, and recall it for further editing. 


‘The tutorial gives instructions on how to invoke MicroEMACS, how fo name a text 
file, and the meaning of the information in the MicroEMACS command line. 


‘An exercise text is presented, and instructions on how to type in the text and save it 
are given. 


‘A number of commands can be used to move the cursor around the screen, <ctrl-F> 
and <ese>F move the cursor forward on the line, <ctel-B> and, <ese>1 move the cur~ 
sor backwards on the line. <ctrl-P> and <ctrl-N> move the cursor to the previous OF 
next lines, respectively. <ctrl-A> and <etrl-E> move the cursor to the beginning or 
the end of the line, respectively, <esc><and <esc>> move the cursor to the beginning 
or end of the text, respectively, <ctrl-V> and <esc>V roll the screen forwards or 
backwards, respectively. 


‘You can erase text in s number of ways. <ctrl-D> and <esc>D erase text to the right 
cdel> and <ese><del> erase text 10 the left, <ctrl-K> erases a line of text (or a por~ 
tion of a line, should the cursor be positioned in the middle of line). <ctrl-D and 
‘edel> delele text, whereas <esc>D, <esc><del>, and <etrl-K> kill text, <ctrl-Y> 
yanks back killed text. 


Text can be block killed and moved from one part of your text to another, To mark a 
block of text for killing, first type <ctrl-@> at one end, then move the cursor to the 
other end. Typing <ctrl-W> kills the marked block of text, and <etrl-Y> yanks back 
killed text. 


The following commands allow the user to block-kill and move text. <etrl-@> sets a 
mark; <etrl-W> deletes all text between the mark and the cursor. <ctrl-Y> yanks 
back the block-killed text wherever the cursor is positioned. 


Specific commands capitalize, uppercase, and lowercase words: <esc>C capitalizes & 
word; <ese>L lowercases 2 word; and <ese>U uppercases a word. <ctrl-T> allows you 
to transpose characters automatically, and <ctrl-L> redraws a scrambled screen, The 
word wrap feature can be adjusted using the command <ctrl-X>F. 


Words or parts of words can be searched for either forwards or backwards through 
the text: <escoS searches forward, and <esc>R searches backwards. <etel-G> cancels 
these commands. 
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Finally, <ctrl-X><ctrl-S> saves text to the file named on the command line; <ctrl- 


‘Xp<ctrl-C> allows the user to exit from MicroEMACS without saving text; and <ctrl- 
‘Z> saves text and moves you back into msh. 
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10, Introduction to Advanced Editing 


‘The second half of this tutorial, chapters 10 through 16, will introduce the advanced 
Features of the MicroEMACS interactive screen editor, 


The techniques described here will help you execute complex editing tasks with mini~ 
mal trouble. You will be able to edit more than one text at a time, display more than 
one text on your screen at a time, enter a long or complicated phrase repeatedly with 
only one keystroke, and give commands to msh without having to exit from 
MicroEMACS. 


Before beginning, however, you must prepare a new text file-you were probably a 
litle tired of watermeton by now, anyway 


ype the following command to msh: 
se text? 


‘This text has been included on the floppy disks that contained there is no need 10 
retype it. Within a moment, text2 will appear on your screen, as Follows: 


From the "Devit's Dictionary: 
‘A penny raved is a penny to squander. 

‘A ban Ta known by the company he orgenizes. 
Aird (n the hand is worth what 1 will bring. 
Think twice before you speak to a friend in need. 
He Laughs best we feughe Le 

Least said fa soonest dieavoued. 

Speak of the Devil ond he will hear about (x. 

Of two evils choose to De the least. 

Strike wille your erployer has a big contract. 
Where there's e will there’s @ won't. 
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11, Arguments 


‘Most of the commands described in the first part of this tutorial can be used with ar- 
guments, An argument is a subcommand that tells MicroEMACS to execute a com- 
mand repeatedly, With MicroEMACS, arguments are introduced by striking <etrl- 
U>. 


Arguments—default values 


By itself, <etrl-U> sets the argument at four. To illustrate this, first type the next line 
command <etrl-N>. By itself, this command moves the cursor dawn one line, from 
‘being over the F in the word From on line 1, to being over the A at the beginning of 
fine 2. 


Now, type <etrl-U>, MicroEMACS replies with the message: 
args 4 


Now type <ctrl-N>. The cursor jumps down four lines, from the letter A in line 2 to 
the letter Hl of the word He at the beginning of line 6. 


‘Type <etrl-U>, The line at the bottom of the screen again shows that the value of the 
argument is 4, Type <etrl-U> again, Now the line at the bottom of the screen reads: 


aes 16 
‘Type <etrl-U> once more. The line at the bottom of the screen now reads: 


Arar 6 


Each time you type <etel-Us, the value of the argument is multiplied by four. Type 
the forward command <ctrl-F>. The cursor has jumped ahead 64 characters, and is, 
now under the period at the end of line 7, 


Selecting values 

Naturally, arguments do not have to be powers of four. You can set the argument to 
whatever number vou wish, simply by typing <etrl-U> and then typing in the number 
you want, 


For example, type <etrl-U>, and then type 3. The line at the bottom of the screen 
now reads: 


tea 3 


Type the delete command <esc><del>, MicroEMACS has deleted three words to the 
left. 
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Arguments can be used to increase the power of any cursor movement command, or 
Any kill or delete command (with the sole exception of <ctrl-W>. the Alock kill com~ 
mand). 


Deleting with arguments—an exception 


Killing-and deleting were described in the first part of this tutorial. They were said 
to differ in that text that was killed was stored in a special arca of the computer and 
could be yanked back, whereas text that was deleted was erased autright. However, 
there ig one exception to this rule: any text that is deleted using an argument can also 
bbe yanked back. 


Move the cursor to the upper left-hand corner of the screen by typing the hegin (ext 
command <ese><. Then, type <ctrl-U><ctrl-D>. Note that the word From has disap- 
peared, Move the cursor to the right until it is between the words Devil's and Dic~ 
tionary, then type <ctrl-Y>. The word From has been moved within the line (al~ 
though the spaces around it have not been moved). This function is very handy, and 
should greatly speed your editing, 


Remember, too, that unless you move the cursor between one set of deletions and 
another, the computer's storage area will not be erased, and you may yank back 
jumble of text, 


Arguments—exercises 


‘The next few exercises show how arguments can be used to make your editing com- 
mands more powerful and efficient, Before beginning, type <ese>< to move the cur~ 
sor to the upper left-hand corner of your screen. 


1, Lowercase the word Devil in fine 8, Use no more than three commands. (<etel-U> 
plus a number and command counts as one command.) 


Solution: To move the cursor, type <ctrl-U>T<ctrl-N>, then <ctrl-U>3 <ese>F. 
Then type <ese>L. 


2. Kill the last four fines of the text. Use no more than two commands, 
Solution; To move the cursor, type <ctrl-A>, Then type <ctrl-U><etrl-K>, 


3. Make two copies of the killed lines at the top of your text, Use no more than two 
commands. 


Solution: To move the cursor, type <ese><. Then type <etrl-U>2<ctrl-Y>, 


4, Finally, delete the last 23 characters of the second line of text. Use no more than 
four commands. 
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Solution; To move the cursor, type <ese><, <ctrl-N>, <ctrl-E>, and then <etl- 
Ur23<del>. 
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12. Buffers and Files 
Before beginning this section, replace the changed copy of the text on your screen 
with a fresh copy. Type the guit command <ctrl-X><ctrl-C> to exit from 
MicroEMACS without saving the text; once the msh prompt appears, return to 
‘MicroEMACS 
by typing: 

ine text? 


Now look at the status line at the bottom of your screen. Tt should appear as follows: 


s+ ST WierOEMACS V1.2 <> Text - Files text2 


‘As noted in the first half of this tutorial, the name on the left of the command line is 
{hat of the program. ‘The name in the middle is the name of the buffer with which 
you are-now working, and the name to the right is the name of the file from which 
you read the text. 


Definitions 


A file ia text that has been given @ name snd has been permanently stored by your 
Computer. A buffer is a portion of the computer's memory that has been set aside for 
ou to use, that may be given a name, and into which you can put text temporarily. 
You can put text {nto the buffer by typing it in from your keyboard or by copying it 
‘rom a file. 


Unlike a file, a buffer is not permanent: if your computer were to stop working 
(because you turned the power off, for example), a file would not be affected, but 8 
buffer would be erased. 


You must name your files because you work with many different files, and you must 
hhave tome way (0 tell them apart. Likewise, MicroEMACS allows you to name your 
buffers, because MicroEMACS allows you to work with more than one buffer ata 
time. 


File and buffer commands 


MicrcEMACS gives you a number of commands for handling files and buffers. The 
following display summarizes them. 
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<etrl-X><etrI-W> Write text to file 
<ctrl-X><ctrl-F> Rename file 


<ctrl-X><ctrl-R> _Replace buffer with named file 
<ctrl-X><etrl-V> Switch buffer or create a new buffer 


<ctrl-X>K Delete a buffer 
<ctrl-X><etrl-B> Display the status of each buffer 


Write and rename commands 


‘The write command <ctrl-X><ctrl-W> was introduced earlier, when the commands 
for saving text and exiting were discussed. To review, <ctrl-X><ctrl-W> changes the 
name of the file into which the text is saved, and then writes a copy of the text into 
that File. 


Type <etrl-X><ctrl-W>, MicroEMACS responds by printing 


Weite files 


on the last line of your screen. 
Type Junkfile, then a carriage return. Two things happen: First, MicroEMACS 
writes the message 


rote 11 Lines) 


at the bottom of your screen. Second, the name of the file shown on the status line 
has changed from text2 to junkfile. MicroEMACS is reminding you that your text 
will be saved from now on to the file Junkfile, unless you change the file name once 
again, 


The file rename command <etrl-X><etrl-F> allows you rename the file to which you 
are saving text, withour automatically writing the text to it. Type <etel-X><ctrl-F>. 
MicroEMACS will reply with the prompt: 


None: 
Now type text2, Note that MicroEMACS does no! send you a message that lines were 


written to the file; however, the name of the file shown on the status line has changed 
from junkfile back to text2, 
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Replace text in a buffer 
“The replace command <ctrl-X><ctrl-R> allows you to replace the text in your buffer 
with the text taken from another file. 


‘Suppose, for example, that you had edited text2 and saved it, and now wished to edit 
text1, You could exit from MicroEMACS, then re-invoke MicroEMACS for the file 
text, but this is cumbersome, A more efficient way is to simply replace the text2 in 
your buffer with text. 


Type <ctrl-X><etrl-R>, MicroEMACS replies with the prompt: 


Read file: 


Type textl, Notice that text2 has rolled away and been replaced with textl. Now, 
check the status line, Notice that although the name of the buffer is still text2, the 
name of the file has changed to textl, You can now edit textl; when you save the 
edited text, MicroEMACS will copy it back into the file textI—unless, of course, you 
choose to rename the file. 


Visiting another buffer 


‘The last command of this set, the visit command <etrl~X><etrl-V>, allows you to, 
create more than one buffer at a time, to jump from one buffer to another, and move 
text between buffers. This powerful command has numerous features. 


Before beginning, however, straighten up your buffer by replacing text! with text2, 
‘Type the replace command <ctrl-X><ctrl-R>; when MicroEMACS replies by asking 


Read fle? 


at the bottom of your screen, type text2. 
You should now have the file text? read into the buffer named text2. 


Now, type the visit command <ctel-X><ctrl-V>. MicroEMACS replies with the 
prompt 


Viett filer 

at the bottom of the screen, Now type textl. Several things happen, text? rolls off 
the screen and is replaced with text]; the status line changes to show that both the 
buffer name and the file name are now text; and the message 


Read 16 Linesd 
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appears at the bottom of the screen. 


‘This does not mean that your previous buffer has been erased, as it would have been 
had you used the replace command <ctrl-X><ctrl-R>. text2 is still being kept “alive” 
in a buffer and is available for editing; however, it is not being shown on your screen 
at the present moment. 


Type <etrl-X><etrl-V> again, and when the prompt appears, type text2. text! scrolls, 
off your screen and is replaced by text2, and the message 


told butfert 


appears at the bottom of your screen. You have just jumped from one buffer to 
‘another. 


Move text from one buffer to another 


‘The visit command <ctrl-X><etel-V> not only allows you jump from one buffer to. 
another, it allows you to move fext from one buffer to another as well. The following 
example shows how you can do this. 


First, kill the first ine of text2 by typing the kill command <ctrl-K> twice, This 
removes both the line of text and the space that it occupied; if you did not remove the 
space as well the line itself, no new line created for the text when you yank it back, 
Next, type <ctrl-X><etrl-V>; when the prompt 


Viele files 


appears at the bottom of your screen, type text. When text! has rolled onto your 
screen, type the yank back command ‘ctrl-¥>. The line you killed in text2 has now 
been moved into text. 


Checking buffer status 


‘The number of buffers you can use at any one time is limited only by the size of your 
computer. You should create only as many buffers as you need to use immediately; 
this will help the computer run efficiently. 


To help you keep track of your buffers, MicroEMACS has the buffer status command 
<ctrl-X><ctrl-B>, Type <etrl-X><etrl-B>. Note that the status line has moved up to 
the middle of the of the screen, and the bottom half of your screen has been replaced 
with the following display. 
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Size gutter 


i 
+ 9z0 text text 
+ 423 texte tent? 


‘This display is called the buffer status window. The use of windows will be discussed 
more fully in the following section. 


‘The letter C over the leftmdst column stands for Changed. An asterisk on a line in- 
dicates that the buffer has been changed since it was last saved, whereas a space 
‘means that the buffer has not been changed. Size indicates the buffer’s size, in num- 
ber of characters; Buffer lists the buffer name, and File lists the file name. 


Now, kill the second line of textI by typing the kil! command <etrl-K>, then type 
‘<ctrl-X><etrl-B> once again, Note that size of the buffer textl has been reduced 
from 913 characters to 882, to reflect the decrease in the size of the buffer. 


‘To make this display disappear, type the one window command <ctrl-X>1. This com- 
mand will be discussed in full in the next chapter. 


Renaming a buffer 
One more point must be covered with the visit command, msh will not allow you to 


have more than one file with the same name, in order to avoid confusion; for the 
same reason, MicroEMACS will not allow you to have more than one bu//er with the 
same namie, 


Ordinarily, when you visit a file that is not already in a buffer, MicroEMACS will 
create a new buffer and give it the same name that the file you are visiting has. 
However, if for some reason you already have a buffer with the same name as the file 
you wish to visit, MicroEMACS will stop and ask you to give a new, different name 
to the buffer it is creating. 


For example, suppose that you wanted to visita new file called sample, perhaps from 
another directory, but you already have a buffer named sample. MicroEMACS would 
stop and give you this prompt at the bottom of the screen: 


fuffer name: 


When you named this new buffer, MicroEMACS would proceed to read the file text2 
into it. 
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Delete a buffer 


If you wish to delete a buffer, simply type the delete buffer command <ctrl-X>K, 
‘This command will allow you only to delete a buffer that is hidden, not one that is 
being displayed. 


‘Type <etrl-X>K, MicroEMACS will give you the prompt: 
KILL buffer: 
‘Type text2, Because you have changed the buffer, MicroEMACS asks: 
Diseard chenges ty/rd? 
‘Type y, and then type the buffer status command <ctrl-X><ctrl-B>; the buffer status 


window will no longer show the buffer text2. Note that although the prompt refers to 
killing a buffer, the buffer is in fact deleted and cannot be yanked back. 


Summary 


‘These buffer and file commands allow you to edit more than one text at once, and 
move text between buffers and files. Just how useful these commands are will be 
seen when you cover the next topic, windows, 
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13. Windows 
Before beginning this section, it will be necessary to create a new text file. Exit from 
MicroEMACS by typing the quit command <ctrl-X><ctrl-C>; then reinvoke 
MicroEMACS for the text file text? 

with the command: 


ve text 


Now, copy text2 into a buffer by typing the visit command <etrl-X><ctrl-V>. When 
the message 


Visit file: 


appears at the bottom of your screen, type text2. MicroEMACS will read text? into a 
buffer, and show the message 


Rend 11 Linea 


at the bottom of your screen. 


Finally, copy @ new text, called text3, into a buffer. Type <ctrl-X><ctrl-V> again. 
When MicroEMACS asks which file to visit, type text3, The message 


Read 92 Vines 


will appear at the bottom of your screen. 
‘The first sereenful of text will appear as follows: 


MicroEMACS Screen Editor Tutorial, ch. 13 


From "oulLiverts Travets! 

1 said there var = society of men among us, 
bred up from their youth in the art of proving 
by vords multiplied for the purpose, that 
white ie Black, ond Black is shite, eccording 
‘a they are paid. To this society all the rest 
‘of the peopte are siaves. 

"For example. if ay neighbor hath » mind to my 
‘com, he hires @ Lowyer to prove that he ought to 
hhave my cow fros me. 1 aust then hire another to 
defeed my right; it being ageirst ati rules of law 
that any mun should be et loved to speak for himself. 
Now in this case, I who om the true omer (Te under 
tuo great disadvantages. First, my lower being 
practiced almost tram his cradie in defending 
falsehood is quite aut of hie element shen he vould 
bbe an advocate for justice, which as an office 
unnatural, he always atteepts with grest aukwardhees, 
Hf not (liewiLL. The second disadvantage is that my 
lawyer must proceed with great caution, or else he 
WILL be reprimanded by the judges, and’ abhorred by 
Nia broxhean, ae ane who would Leasen the pease 

‘ST WicrOERACS Vi.2 => texts -* File: texts) 


AL this point, text3 is on your screen, and text! and text? are hidden. 


You could edit first one text and then another, while remembering just how thi 
stood with the texts that were hidden; but it would be much easier if you could dis 
play all three texts on your screen simultaneously. MicroEMACS allows you to do. 
just that, by using windows. 


Window commands 


A window is a portion of your screen that is set aside and can be manipulated it 
dependently from the rest of the screen, MicroEMACS's commands for manipul 
windows are summarized in the following display. 
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<etrl-X>2 Create a window 


<ctrl-X>1 Delete extra windows 
<etrl-X>N Move to next window 
<ctri-X>P ‘Move to previous window 
“eetrl-X>Z Enlarge window 
<ctrl-X><ctrl-Z> Shrink window 
<ottl-X><etel-N> Scroll down 


<ctrl-X><ctrl 


I-P> Scroll up 


<es Move within window 
<ctl-X>B Switch buffer 


Creating windows and moving between them 


‘The best way to grasp how a window works is to create one and work with it, Type 
the create a window command <ctrl-X>2. 


‘Your screen is now divided into two parts, an upper and a lower, The same text is in 
each part, and the command lines give text3 for the buffer and file names. Also, note 
that you still have only one cursor, which is in the upper left-hand corner of the 
screen, 


‘The next step is to move from one window to another. 

‘Type the next window command <ctrl-X>N. Your cursor has now jumped to the up- 
per left-hand corner of the lower window. 

Type the previous window command <ctrl-X>P, Your cursor has returned to the up- 
per left-hand corner of the top window. 


Now, type <ctrl-X>2 again. The window on the top of your screen is now divided 
into two windows, for a total of three on your screen. Type <etrl-X>2 again, The 
window at the top of your screen has again divided into two windows, for a total of 
four. 


It is possible to have as many as 1] windows on your screen at one time, although 
each window Will show only the contro! line and one or two lines of text, Note that 
neither <ctrl-X>2 nor <etrl-X>1 can be used with arguments. 


Now, type the one window command <etrl-X>1. Note that all of the extra windows 
have been eliminated, or closed. 
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Enlarging and shrinking windows 


When MicroEMACS creates « window, it divides the window in which the cursor is 
positioned into half. You do not have to leave the windows at the size MicroEMACS 
creates them, however. If you wish, you may adjust the relative size of each window 
von your sereén, using the enlarge window and shrink window commands. 


Type <ctrl-No2 twice. Your screen is now divided into three windows: two in the. 
top half of your screen, and the third in the bottom half. 


Now, type the enlarge window command <ctrl-X>Z. The window at the top of your 
screen is now one line bigger, because it has borrowed a line from the window below 
it. Type <etrl-X>Z again. Once again, the top window has borrowed a line from the 
middle window. 


Now, type the next window command <ctrl-X>N, to move your cursor into the mid~ 
dle window. Again, type the enlarge window command <etrl-X>Z. The middle win- 
dow has borrowed a line from the bottom window, and is now one Tine larger. 


The enlarge window command <ctrl-X>Z allows you to enlarge the window your cur= 
sor is in by borrowing lines from another window, provided that you do not shrink 
that other window out of existence, Every window must have at least two lines in it, 
‘one command line and one line of text. 


‘The shrink window command <ctrl-X><ctrl-Z> allows you to decrease the size of a 
window. Type <etrl-X><etrl-Z>. The present window is now one line smaller, and 
the lower window is one tine larger. because the line borrowed earlier has been 
returned, 


‘The enlarge window and shrink window commands can also be used with arguments 
introduced with <etel-U>. However, remember that MicroEMACS will not accept 
an argument that would shrink another window out of existence. 


Displaying text within a window 


Displaying text within the limited area of a window can present special problems. 
‘The view commands <etsl-V> and <ese>V will roll window-sized portions of text up 
or down, but you may become disoriented when a window shows only four or five 
lines of {ext at a time, Therefore, three special commands are available for displaying 
text within a window. 


‘Two commands allow you to move your text by one line at a time, or scroll it: the 


scroll up command <etrl-X><ctrl-N>, and the scrol! down command <ctrl-X><ctrl- 
Ps 
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‘Type <ctrl-X>-<etrl-N>. Note that the line at the top of your window has vanished, a 
now line has appeared at the bottom of your window, and the cursor is now at the 
beginning of what had been the second line of your window. 


Now type <etrl-X><ctrl-P>. The line at the top that had vanished earlier has now 
returned, the cursor is at the beginning of it, and the line-at the bottom of the win- 
dow has vanished, These commands allow you to move forward in your text slowly, 
30 that you do not become disoriented. 


Both of these commands can be used with arguments introduced by <ctrl-U>. 


‘The third special movement command is the move within window command <esco* 
This command moves the line your cursor is on to the top of the window. 


To try this out, move the cursor down three lines by typing <etr-U>3.etrl-N>., then 
type <esc>!, (Be sure to type an exclamation point “', not a numeral one ‘1°, or 
nothing will happen.) Note that the line to which you had moved the cursor is now 
the first line in the window, and three new lines have scrolled up from the bottom of 
the window, You will find’ this command to be very useful as you become more ex- 
perienced at using windows, 


‘All three special movement commands can also be used when your screen has no exira 
windows, although you will not need them as much. 


One buffer 


Now that you have been introduced to the commands for manipulating windows, you 
can begin to use windows to speed your editing, 


‘To begin with, scroll up the window you are in until you reach the top line of your 
text, You can do this either by typing the scroll up command <ctrl-X><etrl-P> 
several times, or by typing <ese><. 


Kill the first line of text with the Ail/ command <ctrl-K>. Note that the first line of 


text has vanished from all three windows, Now, type <ctrl-Y> to yank back the text 
you just killed. The line has reappeared in all three windows. 


The main advantage to displaying one buffer with more than one window is that exch 
window can display a different portion of the text. This can be quite helnful if you 
are editing or moving a large text, 


To demonstrate this, do the following: First, move to the end of the text in your 
present window by typing the end of text command <esc>>. Kill the last four lines, 


‘You could move the killed lines to the beginning of your text by typing the begining 
of text command <esc><; however, it is more convenient simply t0 type the ext win— 
dow command <ctrl-X>N, which will move you to the beginning of the text as dis- 
played in the next window. Note that MicroEMACS remembers a different cursor 
position for each window. 
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Now yank back the four killed lines by typing <ctrl-Y>. You can simultaneously ob- 
serve that the lines have been removed from the end of your text and that they have 
been restored at the beginning. 


Multiple buffers, 


Windows are especially helpful when they display more than one text. Remember 
that at present you are working with three buffers, named text, text2, and text3, al- 
though your screen is displaying only text3. To display a different text ina window, 
use the switch buffer command <ctel-X>B. 


‘Type <ctrl-X>B. When MicroEMACS asks 


we butter: 


at the bottom of the screen, type text. The text in your present window will be 
replaced with text!. Note that the command line in that window has changed, t00, to 
reflect the fact that the buffer and the file names are now text. 


Moving and copying text among buffers 


As you can see, it is now very easy to copy text among buffers, To see how this is 
done, first kill the first line of textl by typing the <ctrl-K> command twice, Yank 
back the line immediately by typing <ctrl-¥>. Remember, the line you killed has not 
heen erased from its special storage area, and may be yanked back any number of 
times. 

Now, move to the previous window by typing <ctrl-X>P, then yank back the killed 
line by typing <ctrl-Y>. This technique can also be used with the block kill command 
‘<ctrl-W> to move large amounts of text from one buffer to another. It also allows 
you to capy text from one window to another. 


Checking buffer status 

‘The buffer status command <ctel-X><ctrl-B> can be used when you are already dis- 
playing more than one window on your screen. 

When you want to remove the buffer status window, use either the one window com- 
mand <ctrl-X>1, or move your cursor into the buffer status window using the next 
window command <ctrl-X>N and replace it with another buffer by typing the switch 
buffer command <ctrl-X>B. 
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Saving text from windows 


“The Final step is to save the text from your windows and buffers. Close the lower two 
THe Jaual with the one window command <ctrl-X>1, Remember, when you close 3 
wiegow the text that it displayed is still kept in a buffer that is hidden from your 
screen, For now, do nor save any of these altered texts. 


When you use the save command <ctrl-X>-<etrl-S>, only the text in the window in 
When Yhe cursor is position will be written to its file. If only one window is dis- 
played on the screen, the save command will save only its text 


If you made changes to the text in another buffer. such as moving portions of it to 
another buffer, MicroE MACS will ask 


uit ty/nd 


If you answer ‘n', MicroEMACS will save the contents of the buffer you are currently 
Uiguaying by writing them (o your disk, but it wil jgnore the contents of other butt 
Giplgnd your cursor will be returned to its previous position in the text. If you 
are a tyh MigroEMACS again will save the contents of the current buffer, and i8- 
ane we esther buffers, but you will exit from MicroEMACS and return to msh. 


Exercises 
“The following, exercises will help you master the use of windows and buffers., Before 


{you begin, exit from MicroEMACS by typing the quit command ctel-X><ctrl-C>, 


1. Invoke MicroEMACS to edit textl. Display text? in a separate window, Copy the 
Feo recat textl to text2, Destroy textl"s buffer. Exit fram MicroEMACS 
without saving the text. 


Solution: To invoke MicroEMACS for text] use the mouse to position the cursor Ook 
Soluilon: Nelled ME-TTP, and press the button twice, when the Open Application 
box appears, type in the mame of the file to be edited, fextl, and then press the car- 
page return key. Before text? can be displayed on a separate window, 1 mus, be 
Cotted into a buffer, again, type the visit command <ctrl-X><ctrl-V> When 
MicroEMACS asks 


visit 


type text2, 


When text2 has been copied into its buffer, type the create window command <elt- 
When teva ti tewtt into the window with the switch bu/fer command <ctrl-X>B. 
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To copy the top four lines from text to text2, first kill the first four lines by typing, 
<ctrl-U>4 <ctri-K>_ Then yank them back immediately by typing <ctrl-Y>; jump to, 
text2's window by typing the next window command <ctrl-X>N, and finally yank 
back the four killed lines again by typing <etrl-Y>. 


‘To destroy the buffer holding the copy of textl, type the one window command <ctrl~ 
‘Nol, then type the delete buffer command <ctrl-X>K. When MicroEMACS asks 
Kit buffers 


type text. When MicroEMACS asks 


Discard changes. ty/nl? 
type y. 
Finally, to exit without saving text, type the quit command <etrl-X><etrl-C>, 


2. Display textl, text2, and text3 in three equally sized windows, Scroll through each 
text in turn. Check the status of the buffers to see if any were altered, then exit from, 
MicroEMACS without saving the texts. 


Solution; Invoke MicroEMACS to edit textt by typing 
me text 


Copy fext2 and text3 into buffers by using the visir command <etel-X><ctrl-V> 
twice. 

Create three windows on your screen by typing the create a window command <ctrl- 
Ne twice, 


Move among the windows by using the next window command <etrl-X>N and the 
previous window command <ctel-X>P; then make sure the windows are of even size by 

1g the enlarge window command <etrl-X>Z and the shrink window command 
<ctrl-X><etrl-Z>. 


Read textl and text2 into your extra windows by using the switch buffer command 
ctrl-X>B, 


To scroll through the texts, use the scroll down command <ctrl-X><ctrl-N> and the 
scroll up command <ctrl-X><ctrl-P>. 


When you are done scrolling, check the buffers’ status with the buffer status com- 
mand <ctrl-X><ctrl-B>, Close the buffer status window by typing the one window 
command <etel-X>1. 


Exit fram MicroEMACS by typing the quit command <etrl-X><etrl-C>. 
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14. Keyboard Macros and Search and Replace 


‘Another helpful feature of MicroEMACS is that it allows you to create a keyboard 
macro. 


Before beginning this section, reinvoke MicroEMACS to edit text3 by typing the 
command 


we text 


‘The term macro means 2 number of commands or characters that are bundled together 
undera common name. Although MicroEMACS allows you to create only one macro 
At a time, this macro can consist of 8 common phrase or a common command or series 
‘of commands that you use while editing your file. 


Keyboard macro commands 
‘The keyboard macro commands are as follows: 

etrl-X>(—_ Begin macro collection 

xetrl-X>) End macro collection 

xetrl-X>E Execute macro 
‘To begin to create a macro, type the begin macro command <ctrl-X>(. Be sure to 
type an open parenthesis ‘(', not a numeral ‘9'. MicroEMACS will reply with the 
message 

etart macro? 
Type the following phrase: 


Interactive screen editor 


‘Then type the end macro command <ctrl-X>). Be sure you type a close parenthesis 
+) not a numeral ‘0’. MicroEMACS will reply with the message 


ter macro 
Move your cursor down two lines and execute the macro by typing the execute macro 


Command <etrl-X>E. ‘The phrase you typed into the macro has been inserted into 
your text 


Should you give these commands in the wrong order, MicroEMACS will warn you 
that you are making a mistake. For example, if you open a keyboard macro by typing 
MUSH Nm(, and then attempt to open another keyboard macro by again typing <ctrl- 
X>(, MicroEMACS will sey: 
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Not now 


Should you accidentally open a keyboard macro, or enter the wrong commands into it, 
‘you can cancel the entire macro simply by typing <etrl-G>. 


Replacing « macro 


To replace this macro with anather, go through the same process. Type <etrl-X>(, 
Then type the buffer status command <ctrl-X><etrl-B>, and type <ctrl-X>), 
Remove the buffer status window by typing the one window command <ctrl-X> 1, 


Now execute your keyboard macro by typing the execute macro command <etrl-X>E. 
‘The buffer status command has executed once more. 


Note that whenever you exit from MicroEMACS, your keyboard macro is erased, and 
must be retyped when you return, 


Search and replace 


MicroEMACS also gives you a power function that allows you to search for string 
and replace it with a keystroke, You can do this by executing the search and replace 
command <ese>%, 


To see how this works, first move to the top of the text file by typing <ese><; then 
type type <ese>%, You will see the following message at the bottom of your screet 


old strings 
‘Asan exercise, type lawyer, MicroEMACS will then ask: 

New string: 
Type doctor, and press the carriage return. As you can see, MicroEMACS jumps to 


the first occurrence of the string lawyer, and prints the following message at the bot- 
tom of your screen: 


Suery replace {Lawyer} -> dectord 
MicroEMACS is asking if it should procede with the replacement. Typing a carriage 
return will display bottom of your screen the options that are available to you, as 
follows: 


<SP1)2 replace, £3 rep-end, In) dont, (11 repl rast <a> gute 


‘The options are as follows: 
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“Typing « space or a comma will execute the replacement, and move the cursor to the 
Typing a space ot the old string, in this case, it will replace lawyer with doctor, and 
move the cursor to the next occurrence of lawyer. 

‘Typing a period *? will replace this one occurrence of the old string, and end the 
qoPINS Ad replace procedure; in this example, typing # period ‘will replace this one 
Securrence of lawyer with doctor and end the procedure. 

‘Typing the letter ‘n’ tells MioroOEMACS rto! to replace Init instance of the old string, 
Typing the Tete next occurrence of the old string; in this case, typing Sn? will not 
Maplace lawyer with doctor, and the cursor will jump to the next place where lawyer 
occurs. 


Typing an exclamation point‘? tells MicroEMACS to repises all instances of the old 
sree ih the new string, without bothering to check with You a0y further, In this 
sing Je, typing "Twill replace all instances of lawyer with doctor without further 
queries from MicroEMACS. 


Finally, typing <etel>-G aborts the search and replace procedure. 
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15, Sending Commands to msh 


‘The last commands you need to learn are the program interrupt commands <etrl-X>! 
and <ctrl-C>_ These commands allow you to interrupt your editing, give a command. 
directly to msh, and then resume editing without affecting your text in any way. 


The command <ctrl-X>t allows you to send one to the operating system. To see how. 
this command works, type <ctel>!, Note that the prompt ! has appeared at the bot- 

tom of your screen. Type Is. Observe that the directory’s table of contents scrolls 
across your screen, followed by the message fend], To return to your editing, simply 
type a carriage return, ‘The interrupt command <etrl-C> suspends editing in~ 
definitely, and allows you to send sn unlimited number of commands to the operating 

system, To see how this works, type <ctrl-C>, After a moment, the msh prompt will 
appear at the bottom of your screen, Type date. msh will reply by printing the time 

and date. To resume editing, then simply type exit. 


If you wish, you can suspend MictoEMACS's operation, tell msh to invoke another 
copy of the MicroEMACS program, edit a file, then return to your previous editing, 
To see how this is done, type <etel-C>. When the prompt appears at the bottom of 
your screen, type 


re text? 


It doesn't matter that you are already editing textl. MicroEMACS will simply copy 
the texil file into a new buffer and let you work as if the other MicroEMACS 
Program you just interrupted never existed. 


Exit from this second MicroEMACS program by typing the uit command <ctel~ 
X><ctrl-C>. Then type exit. Your original MicroEMACS program has now been 
resumed, Note, however, that none of the changes you made in the secondary 
MicroEMACS program will be seen here. 


It is not a good idea to use multiple MicroEMACS programs to edit the same program: 
it is too easy to become confused as to which edits were made to which version, 


The only time this is advisable, is if you wish to test to see how a certain edit would 
affect your text: you can create a new MicroEMACS program, test the command, and_ 
then destroy the altered buffer and return to your original editing program without 
having to worry that you might make errors that are difficult to correct, 


Compiling and debugging through MicroEMACS 


MicroEMACS can be used with the compiletion command ec to give you a reliable 
system for debugging new programs. 


Often, when you're writing a new program, you face the situation where you try to 
compile, only'to have the compiler produce error messages and abort the compilation. 
You must then invoke your editor, change the program, close the editor, and try the 
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compilation over again. This cycle of compilation—editing—recompilation can be 
quite bothersome. 


To remove some of the drudgery from compiling, the ec command has the aulencie 
7° AfieroEMACS option, -A. When you compile with this option, the MicroEMACS 
eee tditor will be invoked automatically if any errors occur. The error oe sist 
generated during compilation will be displayed in one window, and your text in the 
serge with the eursor set at the number of the fine that the compiler indicated had 
the error, 


Try the following example, Use MicroEMACS to.enter the following program, which 
‘you should call error.c: 


maint) ¢ 
printfomelto, word") 
> 


Note that the semicolon was left off of the printf statement, which is an error Now, 
fry compiling error.c with the following ec command: 


ce “A error-e 


You should see no messages from the compiler, because they are all being diverted 
YoU shooter to. be used by MicroEMACS, Then, MicroEMACS will apresr 
automatically, In one window you should see the message: 


3: alssiog 43! 


and in the other you should see your source code for error.e, with the cursor se1 08 
line 3. 


If you had more than one, typing <etrl-X>> would move you 19 the nest ine with an 
Xf you pat Doping <etrl-X>< would return you to the previous error. Note that with 
cree ie ois auch as those for missing braces or semicolons, the compiler cant al- 
Says tel exactly which line the error occurred on, but it will almost always point to @ 
Tine that is near the source of the error. 


Now, correct the error. Close the file by typing <ctrl-Z>. ec will be invoked again 
Now cGeaily,, Compilation will continue either until the program compiles WiNaTt 
geron, or until you exit from MieroEMACS by typing <etrl-U> followed by <ctrl- 
Xe<ctrl-C>. 
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16, Advanced Editing—Conclusion and Summary 


This concludes the tutorial for the MicroEMACS interactive screen editor, 
Congratulations on your diligence in working through it! MicroEMACS and its 
related EMACS-based screen editors are now at your command, and you have ac- 
quired a skill that will serve you well. 


This section introduced the sdvanced editing techniques available with MicroEMACS_ 


Arguments can be used with most cursor movement commands and all text deletion 
commands to set the number of times they execute. The command <ctrl-U> 
introduces arguments, The default for <ctrl-U> is 4, with each subsequent entry of 
<ctrl-U> multiplying the argument by 4. The value of an argument can be changed 
by typing <etrl-Us, followed by an integer. 


‘Text is edited in a buffer, and is copied into a file when the user issues the save com 
mands <etrl-X><ctrl-S> or the write command <etrl-X><ctrl-W>. <ctrl-X><etel-F> 
will rename the file; and <etrl-X><ctrl-W> renames the file and automatically copies 
text to it 


MicroEMACS can handle more than one buffer at a time. <ctrl-X><etrl-V> moves. 
you from one buffer to another, and allows you to create a buffer should the buffer 
you requested not already exist, 


‘<ctrl-X><ctrl-R> replaces the text in a buffer with the text drawn from a specified) 
file. <etrl-X>K deletes a buffer, 

<ctrl-X><ctrl-B> displays information on the status of each buffer. 

‘The screen can be divided into windows, which can display either the same buffer or 
different buffers, <ctrl-X>2 creates a window by dividing the present window in 
half, whereas the command <etrl-X>1 erases all extra windows, 

<etrl-X>Z and <ctrl-X><ctrl-Z> enlarge and shrink windows, respectively. <etrl= 
X+N moves the cursor to the next, or lower, window, whereas <ctrl-X>P moves the 
cursor 10 the previous window, 

<ctrl-X>-<ctrl-N>, <ctrl-X><ctrl-P>, and <ese>! respectively scroll the window up, 
scroll it down, and move the line on Which the cursor rests to the top of the window. 
<ctrl-X>B displays a different buffer within a window. 


MicroEMACS allows you to create a keyboard macro that executes a set of commands. 
or inserts text, <etrl-Xo( opens the macro, <ctrl-X>) closes it, and <etrl-X>E_ 
executes it, 


<ese>% executes a search and replace procedure. 
<ctrl-C> interrupts the operation of MicroEMACS, so that the user can send com= 


mands directly to msh, You can resume working with MicroEMACS by typing <ctel= 
D>. 
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ec: 
MicroEMACS: 678 
command line: 
buffer name: 635 
changed file name: 653 
file name: 635 
file name changed: 662 
interpretation: 634 
commands: 
‘arguments: 658 
block Kill text; 644 
buffer status: 664 
cancel: 652 
capitalization: 646 
cursor movement display: 636 
exiting from MicroEMACS: 653 
file and buffer: 661 
giving ¢. to msh: 678 
increase power: 658, 
keyboard macros: 675 
lowercase: 646 
me: 634 
move text: 644 
program interrupt: 678 
redraw screen: 647 
saving text: 653 
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search and replace: 676 
searching: 650 
switch buffers: 663 
uppercase: 646 
window manipulation: 668 
‘word wrap: 647 
compiling and debugging: 678 
control characters: 631 
control key: 631 
location: 631 
‘copying sample texts: 633 
copying text: 672 
cursor movement: 
arrow keys: 636 


back: 636 
beginning of text: 638 
end of text: 638 


exercises: 638 
forwards: 637 
left: 636 
line position: 637 
move within window: 671 
next line: 637 
previous line: 637 
right: 637 
screen down: 637 
screen up: 637 
scroll down: 670 
scroll up: 670 
strategy: 638 
delete buffer command: 666 


delete key: 641 
delete text: 
exercises: 642 
versus killing: 640 
deleting with arguments: 659 
display: 
capitalization, transpose, redraw: 646 
commands: 650 
file and buffer commands: 661 
keyboard macro commands: 675 
kill and move commands: 644 
Killing and deleting: 640 
movement commands: 636 
text and exiting: 653, 
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window commands: 668 
document: 

beginning a new d.: 634 
‘end macro command: 675 


end of text command: 638 
enlarge window command: 670 
with arguments: 670 
erase text: 640 
by line: 642 
deletion of spaces: 641 
erasing spaces: 641 
to the left: 641 
to the right: 641 
escape key: 631 
location: 631 
execute macro command: 675 
exercises: 
arguments: 659 
buffers: 673 
cursor movement: 638 
delete text: 642 
Kill text: 642 
windows: 673 
yank back text; 642 
exiting from MicroEMACS 653 
extended commands: 653 


file: 
definition: 661 
how differs from buffer. 661 
name on command line: 635 
naming: 661 
rename: 662 
replace buffer with named f: 663 
size: 633 
with windows: 671 
write to new £2 662 
forwards: 
‘end of line: 637 


interactive editor: 
definition: 631 
keyboard macros: 675 
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ill text: 
block: 645 
exercises: 642 
versus deleting: 640 
lowercase text: 646 


macros: 675 

‘me command: 634 

message: 
678 
[Done 650 
[End macro} 675 
fend}: 678 
[Mark set} 645 
[New file} 634 
[Old buffer} 664 
[Read XX lines} 633, 663, 667 
[Start macro: 675 
[Wrap at column XX}: 648 
[Wrote XX lines} 639, 653, 662 
Arg: X: 648, 658 
Buffer name: 665 
Discard changes [y/n]?: 666, 674 
failing i-search forward: 651 
File too large for available memory!; 633 
icsearch forward: 650 


Kill buffer: 666 
‘Name: 662 

Not found: 651 
Nor now: 675 


Reverse search [xxxxx}: 651 

Search:: 651 

Use buffer: 672 

Visit file 663-664, 667 

Write file: 653, 662 
messages: 

New string: 676 

Old string: 676 

Query repiace [oldstring] -> [newstring} 676 
meta characters: 631 
MicroEMACS: 

advanced editing with: 657 

basic editing with: 631 
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beginning to use: 632 
exiting from: 653 
file size: 633 
invoking: 634 
quit without saving text 643 
saving text: 639 
move: 
cursor: 636 
text 644 
text from one buffer to another: 664 
within window comman 
multiple copying of killed text: 644 


next error: 679 
next line command: 637 
number of buffers allowed: 664 


previous error: 679 
previous line command: 637 
program interrupt command: 678 


quit without saving text: 639 
quitting MicroEMACS: 639 


redraw screen: 647 

rename file: 662 

replace buffer with named file: 663 
restore (yank back) killed text: 642 
reverse search: 


sample texts: 
copying: 633 
saving text: 639, 653 
sereen backwards movement: 637 
screen down command: 638 
sereen editor: 
definition: 631 
sereen forward movement 637 
sereen redraw: 647 
sereen up command: 638 
scroll down command: 670 
with arguments: 671 
seroll up command: 670 
with arguments: 671 
search: 
forward: 650 
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reverse: 651 
search and replace command: 676 
shrink window command: 670 
with arguments: 670 
store command: 654 
summary: 
advanced editing: 680 
basic editing: 655, 
switch buffer command: 671 


tab key: 631 
text: 
block kill: 645 
capitalize: 646 
erase: 640 
erase to left: 641 
erase to right: 641 
kill by lines: 642 
lowercase: 646 
move: 644 
move from one buffer to another: 664 
multiple copying of killed t.: 644 
restore (yank back): 642 
saving: 653 
saving t: 639 
uppercase: 646 
write to new file: 653 
yank back (restore): 642 
transpose characters: 647 


uppercase text: 646 


visit command: 663 
creating new file: 667 
moving text between buffers: 664 
prompting for buffer name: 665 


window: 
buffer status: 664 
buffer status command use: 672 
commands, table 7: 668 
copying text among: 672 
definition: 668 
‘enlarge: 670 
exercises: 673 
move within: 671 
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moving text among: 672 
multiple w.: 669 
number possible: 669 
one w: 669 
saving text: 673 
scroll down: 670 
scroll up: 670 
shifting between: 669 
shrink: 670 
use 
using multiple buffers: 67! 

word wrap: 647 

write text to new file: 693, 662 


yank back text: 642, 659 
exercises: 642 
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